Skip to main content

​
ToolDefinition

Defines a tool available to an AI agent. This interface represents the metadata needed to describe a tool in a system prompt. It contains only the declarative information that an AI model needs to understand when and how to use the tool - it does NOT include execution logic. The separation of tool definition from execution follows the principle that system prompts are text sent to the model, while tool execution happens in your application runtime when the model requests to use a tool.

​
Type Definition

export type ToolDefinition<T extends z.ZodType = z.ZodType> = {
  name: string;
  description: string;
  schema: T;
};

​
Properties

​
name
string
required
Unique identifier for the tool. This name is used by the AI model to reference the tool when it decides to use it. Should be descriptive, snake_case, and unique within your toolset.Examples: "get_weather", "search_database", "send_email"
​
description
string
required
Human-readable description of what the tool does and when to use it. This description is shown to the AI model in the system prompt. It should clearly explain the tool’s purpose, what it returns, and any important usage guidelines. Be specific about when the model should choose this tool over others.
​
schema
T extends z.ZodType
required
Zod schema defining the tool’s input parameters. This schema serves dual purposes:
  1. Documents the parameters in the system prompt (via introspection)
  2. Can be used at runtime to validate tool invocation arguments
Use .describe() on schema fields to provide parameter descriptions that will appear in the generated system prompt.

​
Usage Example

import { z } from "zod";

const weatherTool: ToolDefinition = {
  name: "get_weather",
  description: "Retrieves current weather for a location. Use when user asks about weather conditions.",
  schema: z.object({
    location: z.string().describe("City name or address"),
    units: z.enum(["celsius", "fahrenheit"]).optional()
  })
};

​
When to Use

Use ToolDefinition when you:
  • Need to document tools in a system prompt without providing execution logic
  • Want to separate tool descriptions from tool implementations
  • Are building prompts for documentation purposes
  • Plan to handle tool execution separately from prompt generation

​
ExecutableToolDefinition

Extended tool definition that includes execution logic for AI SDK integration. This interface extends ToolDefinition to include an optional execute function that implements the actual tool logic. When tools include execution logic, they can be exported directly to Vercel AI SDK format using .toAiSdkTools() or .toAiSdk().

​
Type Definition

export interface ExecutableToolDefinition<T extends z.ZodType = z.ZodType>
  extends ToolDefinition<T> {
  execute?: (args: z.infer<T>) => Promise<unknown> | unknown;
}

​
Properties

​
name
string
required
Inherited from ToolDefinition. Unique identifier for the tool.
​
description
string
required
Inherited from ToolDefinition. Human-readable description of the tool’s purpose.
​
schema
T extends z.ZodType
required
Inherited from ToolDefinition. Zod schema defining the tool’s input parameters.
​
execute
(args: z.infer<T>) => Promise<unknown> | unknown
Execution function for the tool (optional). When provided, this function implements the actual tool logic. It receives the validated arguments (matching the schema) and returns the tool’s result.The function can be either synchronous or asynchronous (returning a Promise).

​
Usage Example

import { z } from "zod";

const weatherTool: ExecutableToolDefinition = {
  name: "get_weather",
  description: "Get current weather for a location",
  schema: z.object({
    location: z.string().describe("City name")
  }),
  execute: async ({ location }) => {
    const response = await fetch(`https://api.weather.com/${location}`);
    return response.json();
  }
};

​
Integration with AI SDK

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const prompt = new PromptSmith()
  .withIdentity("Weather Assistant")
  .withTool(weatherTool);

const config = prompt.toAiSdk();

const response = await generateText({
  model: openai('gpt-4'),
  ...config,
  prompt: "What's the weather in Paris?"
});

​
When to Use

Use ExecutableToolDefinition when you:
  • Want to combine tool documentation and execution in one place
  • Are integrating with Vercel AI SDK or similar frameworks
  • Need to export tools in a format ready for runtime execution
  • Want the convenience of calling .toAiSdk() to get both prompt and tools

​
Flexibility

The separation remains flexible:
  • Tools without execute are used for documentation only (system prompt)
  • Tools with execute can be used for both documentation and runtime execution

Build docs developers (and LLMs) love

Get started for freeTalk to us