docs: update tool example (vercel#2644)

content/examples/03-node/03-tools/01-call-tool.mdx

@@ -11,6 +11,7 @@ This is useful for extending the capabilites of a language model to either use l
 ```ts
 import { generateText, tool } from 'ai';
 import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
 
 const result = await generateText({
   model: openai('gpt-4-turbo'),
@@ -33,3 +34,120 @@ const result = await generateText({
     'What is the weather in San Francisco and what attractions should I visit?',
 });
 ```
+
+## Accessing Tool Calls and Tool Results
+
+If the model decides to call a tool, it will generate a tool call. You can access the tool call by checking the `toolCalls` property on the result.
+
+```ts highlight="31-44"
+import { openai } from '@ai-sdk/openai';
+import { generateText, tool } from 'ai';
+import dotenv from 'dotenv';
+import { z } from 'zod';
+
+dotenv.config();
+
+async function main() {
+  const result = await generateText({
+    model: openai('gpt-3.5-turbo'),
+    maxTokens: 512,
+    tools: {
+      weather: tool({
+        description: 'Get the weather in a location',
+        parameters: z.object({
+          location: z.string().describe('The location to get the weather for'),
+        }),
+        execute: async ({ location }) => ({
+          location,
+          temperature: 72 + Math.floor(Math.random() * 21) - 10,
+        }),
+      }),
+      cityAttractions: tool({
+        parameters: z.object({ city: z.string() }),
+      }),
+    },
+    prompt:
+      'What is the weather in San Francisco and what attractions should I visit?',
+  });
+
+  // typed tool calls:
+  for (const toolCall of result.toolCalls) {
+    switch (toolCall.toolName) {
+      case 'cityAttractions': {
+        toolCall.args.city; // string
+        break;
+      }
+
+      case 'weather': {
+        toolCall.args.location; // string
+        break;
+      }
+    }
+  }
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+main().catch(console.error);
+```
+
+## Accessing Tool Results
+
+You can access the result of a tool call by checking the `toolResults` property on the result.
+
+```ts highlight="31-41"
+import { openai } from '@ai-sdk/openai';
+import { generateText, tool } from 'ai';
+import dotenv from 'dotenv';
+import { z } from 'zod';
+
+dotenv.config();
+
+async function main() {
+  const result = await generateText({
+    model: openai('gpt-3.5-turbo'),
+    maxTokens: 512,
+    tools: {
+      weather: tool({
+        description: 'Get the weather in a location',
+        parameters: z.object({
+          location: z.string().describe('The location to get the weather for'),
+        }),
+        execute: async ({ location }) => ({
+          location,
+          temperature: 72 + Math.floor(Math.random() * 21) - 10,
+        }),
+      }),
+      cityAttractions: tool({
+        parameters: z.object({ city: z.string() }),
+      }),
+    },
+    prompt:
+      'What is the weather in San Francisco and what attractions should I visit?',
+  });
+
+  // typed tool results for tools with execute method:
+  for (const toolResult of result.toolResults) {
+    switch (toolResult.toolName) {
+      case 'weather': {
+        toolResult.args.location; // string
+        toolResult.result.location; // string
+        toolResult.result.temperature; // number
+        break;
+      }
+    }
+  }
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+main().catch(console.error);
+```
+
+<Note>
+  `toolResults` will only be available if the tool has an `execute` function.
+</Note>
+
+## Model Response
+
+When using tools, it's important to note that the model won't respond with the tool call results by default. This is because the model has technically already generated its response to the prompt: the tool call. Many use cases will require the model to summarise the results of the tool call within the context of the original prompt automatically. You can achieve this by [using `maxToolRoundtrips`](/examples/node/tools/call-tools-with-automatic-roundtrips) which will automatically send toolResults to the model to trigger another generation.