# `tool()`

Tool is a helper function that infers the tool parameters for its `execute` method.

It does not have any runtime behavior, but it helps TypeScript infer the types of the parameters for the `execute` method.

Without this helper function, TypeScript is unable to connect the `parameters` property to the `execute` method,
and the argument types of `execute` cannot be inferred.

```ts highlight={"1,4,9,10"}
import { tool } from 'ai';
import { z } from 'zod';

export const weatherTool = tool({
  description: 'Get the weather in a location',
  parameters: z.object({
    location: z.string().describe('The location to get the weather for'),
  }),
  // location below is inferred to be a string:
  execute: async ({ location }) => ({
    location,
    temperature: 72 + Math.floor(Math.random() * 21) - 10,
  }),
});
```

## Import

<Snippet text={`import { tool } from "ai"`} prompt={false} />

## API Signature

### Parameters

<PropertiesTable
  content={[
    {
      name: 'tool',
      type: 'Tool',
      description: 'The tool definition.',
      properties: [
        {
          type: 'Tool',
          parameters: [
            {
              name: 'description',
              isOptional: true,
              type: 'string',
              description:
                'Information about the purpose of the tool including details on how and when it can be used by the model.'
            },
            {
              name: 'parameters',
              type: 'Zod Schema | JSON Schema',
              description:
                'The schema of the input that the tool expects. The language model will use this to generate the input. It is also used to validate the output of the language model. Use descriptions to make the input understandable for the language model. You can either pass in a Zod schema or a JSON schema (using the `jsonSchema` function).'
            },
            {
              name: 'execute',
              isOptional: true,
              type: 'async (parameters: T, options: ToolExecutionOptions) => RESULT',
              description:
                'An async function that is called with the arguments from the tool call and produces a result. If not provided, the tool will not be executed automatically.',
                properties: [
                  {
                    type: "ToolExecutionOptions",
                    parameters: [
                      {
                      name: 'toolCallId',
                      type: 'string',
                      description: 'The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.',
                    },
                    {
                        name: "messages",
                        type: "CoreMessage[]",
                        description: "Messages that were sent to the language model to initiate the response that contained the tool call. The messages do not include the system prompt nor the assistant response that contained the tool call."
                      },
                      {
                        name: "abortSignal",
                        type: "AbortSignal",
                        description: "An optional abort signal that indicates that the overall operation should be aborted."
                      }
                    ]
                  }
                ]
            },
            {
              name: 'experimental_toToolResultContent',
              isOptional: true,
              type: '(result: RESULT) => TextToolResultContent | ImageToolResultContent',
              description: 'An optional function that converts the result of the tool call to a content object that can be used in LLM messages.',
              properties: [
                {
                  type: 'TextToolResultContent',
                  parameters: [
                    {
                      name: 'type',
                      type: "'text'",
                      description: 'The type of the tool result content.'
                    },
                    {
                      name: 'text',
                      type: 'string',
                      description: 'The content of the message.'
                    }
                  ]
                },
                {
                  type: 'ImageToolResultContent',
                  parameters: [
                    {
                      name: 'type',
                      type: "'image'",
                      description: 'The type of the tool result content.'
                    },
                    {
                      name: 'data',
                      type: 'string',
                      description: 'The base64 encoded png image.'
                    },
                    {
                      name: 'mimeType',
                      isOptional: true,
                      type: 'string',
                      description: 'The mime type of the image.'
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }

]}
/>

### Returns

The tool that was passed in.


## Navigation

- [generateText](/v4/docs/reference/ai-sdk-core/generate-text)
- [streamText](/v4/docs/reference/ai-sdk-core/stream-text)
- [generateObject](/v4/docs/reference/ai-sdk-core/generate-object)
- [streamObject](/v4/docs/reference/ai-sdk-core/stream-object)
- [embed](/v4/docs/reference/ai-sdk-core/embed)
- [embedMany](/v4/docs/reference/ai-sdk-core/embed-many)
- [generateImage](/v4/docs/reference/ai-sdk-core/generate-image)
- [transcribe](/v4/docs/reference/ai-sdk-core/transcribe)
- [generateSpeech](/v4/docs/reference/ai-sdk-core/generate-speech)
- [tool](/v4/docs/reference/ai-sdk-core/tool)
- [experimental_createMCPClient](/v4/docs/reference/ai-sdk-core/create-mcp-client)
- [Experimental_StdioMCPTransport](/v4/docs/reference/ai-sdk-core/mcp-stdio-transport)
- [jsonSchema](/v4/docs/reference/ai-sdk-core/json-schema)
- [zodSchema](/v4/docs/reference/ai-sdk-core/zod-schema)
- [valibotSchema](/v4/docs/reference/ai-sdk-core/valibot-schema)
- [CoreMessage](/v4/docs/reference/ai-sdk-core/core-message)
- [createProviderRegistry](/v4/docs/reference/ai-sdk-core/provider-registry)
- [customProvider](/v4/docs/reference/ai-sdk-core/custom-provider)
- [cosineSimilarity](/v4/docs/reference/ai-sdk-core/cosine-similarity)
- [wrapLanguageModel](/v4/docs/reference/ai-sdk-core/wrap-language-model)
- [LanguageModelV1Middleware](/v4/docs/reference/ai-sdk-core/language-model-v1-middleware)
- [extractReasoningMiddleware](/v4/docs/reference/ai-sdk-core/extract-reasoning-middleware)
- [simulateStreamingMiddleware](/v4/docs/reference/ai-sdk-core/simulate-streaming-middleware)
- [defaultSettingsMiddleware](/v4/docs/reference/ai-sdk-core/default-settings-middleware)
- [simulateReadableStream](/v4/docs/reference/ai-sdk-core/simulate-readable-stream)
- [smoothStream](/v4/docs/reference/ai-sdk-core/smooth-stream)
- [generateId](/v4/docs/reference/ai-sdk-core/generate-id)
- [createIdGenerator](/v4/docs/reference/ai-sdk-core/create-id-generator)


[Full Sitemap](/sitemap.md)