defineTool()

Overview

The defineTool() function defines tools (functions) that language models can call during generation. Tools enable models to access external data, perform calculations, or trigger actions beyond text generation.

Function signature

export function defineTool<TParameters extends SchemaInput>(
    options: ToolDefinition<TParameters>
): ToolDefinition<TParameters>;

type ToolDefinition<TParameters extends SchemaInput = SchemaInput> = {
    name: string;
    description: string;
    parameters: TParameters;
    strict?: boolean;
};

Parameters

string

required

The unique name of the tool. This is what the model uses to identify and call the tool. Should be descriptive and follow snake_case convention (e.g., get_weather, search_database).

string

required

A clear description of what the tool does. This helps the model understand when and how to use it. Should explain the tool’s purpose, expected inputs, and what it returns.

SchemaInput

required

Schema of the tool’s input parameters: a Standard Schema with JSON Schema support, such as a Zod 4.2+ schema, or plain JSON Schema. The model generates arguments matching this schema. Check calls to tools with Standard Schema parameters with validateToolCall().

boolean

Opts this tool into provider-enforced adherence to its parameter schema. Omitted or false keeps the tool non-strict on every provider.

Return value

Returns the same ToolDefinition object that was passed in. This is a type-safe helper that provides IDE autocompletion and validation.

Strict schema enforcement

strict: true opts a single tool into provider-enforced schema adherence. The tool’s schema must fit the strict-capable subset (closed objects whose keys are required, nullable, or defaulted — in Zod, use .nullable() instead of a bare .optional()), which core-ai validates locally before the provider request. Check model.capabilities.tools.strictSchemas before opting tools in. Strict enforcement does not replace runtime validation. Check each call with validateToolCall() before executing the tool. See Strict tool schemas in the tool-calling guide for the schema contract, error reasons, and provider support.

validateToolCall()

Validates the arguments of a tool call with the tool’s own Standard Schema.

function validateToolCall<TParameters extends SchemaInput>(
    tool: ToolDefinition<TParameters>,
    toolCall: ToolCall
): Promise<ToolCallValidation<TParameters>>;

For Standard Schema parameters, it returns the schema’s result, typed with the schema’s output:

{ value } when the arguments match. value is the schema’s output, with defaults and transforms applied.
{ issues } when they do not. Each issue has a message and an optional path. A validator that throws, such as a transform calling new URL(), is reported as an issue too.

For plain JSON Schema parameters, such as tool schemas from an MCP server, it returns undefined: core-ai ships no JSON Schema validator, so validate those arguments yourself. It throws a ValidationError when toolCall is a call to another tool, or when the tool’s parameters are not a usable schema, which a request with the tool rejects too. Send issues back to the model as an error tool result, and run the tool with value, not with the raw ToolCall.arguments. See Validate tool calls for complete examples.

Examples

Basic tool definition

import { defineTool } from '@core-ai/core-ai';
import { z } from 'zod';

const weatherTool = defineTool({
    name: 'get_weather',
    description: 'Get the current weather for a location',
    strict: true,
    parameters: z.object({
        location: z.string().describe('City name or zip code'),
    }),
});

Tool with multiple parameters

const searchTool = defineTool({
    name: 'search_database',
    description: 'Search the product database with filters',
    parameters: z.object({
        query: z.string().describe('Search query'),
        category: z.string().optional().describe('Product category filter'),
        maxResults: z
            .number()
            .min(1)
            .max(100)
            .default(10)
            .describe('Maximum number of results to return'),
    }),
});

Using tools with generate()

import { generate, defineTool } from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';
import { z } from 'zod';

const openai = createOpenAI();
const model = openai.chatModel('gpt-5-mini');

const calculatorTool = defineTool({
    name: 'calculate',
    description: 'Perform mathematical calculations',
    parameters: z.object({
        expression: z.string().describe('Math expression to evaluate'),
    }),
});

const result = await generate({
    model,
    messages: [{ role: 'user', content: 'What is 142 * 89?' }],
    tools: {
        calculate: calculatorTool,
    },
});

if (result.toolCalls.length > 0) {
    const toolCall = result.toolCalls[0];
    console.log('Tool:', toolCall.name);
    console.log('Arguments:', toolCall.arguments);
    // Output: { expression: '142 * 89' }
}

Tool execution loop

import {
    defineTool,
    generate,
    resultToMessage,
    validateToolCall,
} from '@core-ai/core-ai';
import type { Message, ToolCall, ToolResultMessage } from '@core-ai/core-ai';
import { z } from 'zod';

const tools = {
    get_weather: defineTool({
        name: 'get_weather',
        description: 'Get weather for a location',
        parameters: z.object({
            location: z.string(),
        }),
    }),
    get_time: defineTool({
        name: 'get_time',
        description: 'Get current time in a timezone',
        parameters: z.object({
            timezone: z.string().describe('IANA timezone name'),
        }),
    }),
};

// Implement tool handlers. Each validates the call against its own tool and
// gets the typed output of its schema.
type ToolOutput = Pick<ToolResultMessage, 'content' | 'isError'>;

const toolHandlers: Record<
    string,
    (toolCall: ToolCall) => Promise<ToolOutput>
> = {
    get_weather: async (toolCall) => {
        const validation = await validateToolCall(tools.get_weather, toolCall);
        if (validation.issues) {
            return {
                content: JSON.stringify(validation.issues),
                isError: true,
            };
        }
        // Call weather API
        return {
            content: `The weather in ${validation.value.location} is sunny, 72°F`,
        };
    },
    get_time: async (toolCall) => {
        const validation = await validateToolCall(tools.get_time, toolCall);
        if (validation.issues) {
            return {
                content: JSON.stringify(validation.issues),
                isError: true,
            };
        }
        const { timezone } = validation.value;
        const time = new Date().toLocaleString('en-US', {
            timeZone: timezone,
        });
        return { content: `Current time in ${timezone}: ${time}` };
    },
};

const messages: Message[] = [
    { role: 'user', content: "What's the weather in Tokyo?" },
];

let result = await generate({
    model: model,
    messages,
    tools,
});

// Execute tools and continue while the model waits for results
while (result.finishReason === 'tool-calls') {
    messages.push(resultToMessage(result));

    for (const toolCall of result.toolCalls) {
        const handler = toolHandlers[toolCall.name];

        messages.push({
            role: 'tool',
            toolCallId: toolCall.id,
            ...(handler
                ? await handler(toolCall)
                : { content: `Unknown tool: ${toolCall.name}`, isError: true }),
        });
    }

    result = await generate({
        model: model,
        messages,
        tools,
    });
}

console.log(result.content);
// Output: "The weather in Tokyo is sunny, 72°F"

Complex parameters with nested objects

const createEventTool = defineTool({
    name: 'create_calendar_event',
    description: 'Create a new calendar event',
    parameters: z.object({
        title: z.string().describe('Event title'),
        startTime: z.string().datetime().describe('ISO 8601 start time'),
        endTime: z.string().datetime().describe('ISO 8601 end time'),
        attendees: z
            .array(
                z.object({
                    name: z.string(),
                    email: z.string().email(),
                })
            )
            .optional()
            .describe('List of attendees'),
        location: z.string().optional(),
        reminders: z
            .object({
                email: z.boolean().default(true),
                popup: z
                    .number()
                    .min(0)
                    .optional()
                    .describe('Minutes before event for popup'),
            })
            .optional(),
    }),
});

Tool with enum parameters

const analyzeSentimentTool = defineTool({
    name: 'analyze_sentiment',
    description: 'Analyze the sentiment of text',
    parameters: z.object({
        text: z.string().describe('Text to analyze'),
        language: z
            .enum(['en', 'es', 'fr', 'de'])
            .default('en')
            .describe('Language of the text'),
        includeScore: z
            .boolean()
            .default(false)
            .describe('Include numerical sentiment score'),
    }),
});

Multiple Tools in One Call

const tools = {
    search_web: defineTool({
        name: 'search_web',
        description: 'Search the web for information',
        parameters: z.object({
            query: z.string(),
        }),
    }),

    get_stock_price: defineTool({
        name: 'get_stock_price',
        description: 'Get current stock price',
        parameters: z.object({
            symbol: z.string().describe('Stock ticker symbol'),
        }),
    }),

    convert_currency: defineTool({
        name: 'convert_currency',
        description: 'Convert between currencies',
        parameters: z.object({
            amount: z.number(),
            from: z.string().describe('Source currency code'),
            to: z.string().describe('Target currency code'),
        }),
    }),
};

const result = await generate({
    model: model,
    messages: [
        { role: 'user', content: "What's Tesla's stock price in euros?" },
    ],
    tools,
});

// Model might call get_stock_price then convert_currency

Controlling Tool Usage

// Auto: Model decides whether to use tools
const result1 = await generate({
    model: model,
    messages: [{ role: 'user', content: 'Hello' }],
    tools: { get_weather: weatherTool },
    toolChoice: 'auto', // Default
});

// Required: Model must use a tool
const result2 = await generate({
    model: model,
    messages: [{ role: 'user', content: 'Get weather' }],
    tools: { get_weather: weatherTool },
    toolChoice: 'required',
});

// Force specific tool
const result3 = await generate({
    model: model,
    messages: [{ role: 'user', content: 'Get weather' }],
    tools: {
        get_weather: weatherTool,
        get_time: timeTool,
    },
    toolChoice: { type: 'tool', toolName: 'get_weather' },
});

// None: Disable tools
const result4 = await generate({
    model: model,
    messages: [{ role: 'user', content: 'Hello' }],
    tools: { get_weather: weatherTool },
    toolChoice: 'none',
});

Type Safety

The tool definition is fully type-safe:

const userTool = defineTool({
    name: 'get_user',
    description: 'Get user information',
    parameters: z.object({
        userId: z.number(),
        includeProfile: z.boolean().optional(),
    }),
});

// TypeScript knows the parameter types
type ToolParams = z.infer<typeof userTool.parameters>;
// { userId: number; includeProfile?: boolean | undefined }

const handler = async (args: ToolParams) => {
    const userId: number = args.userId; // Type-safe
    const include: boolean | undefined = args.includeProfile; // Type-safe
    // Fetch and return user data
};

Best Practices

Use descriptive tool names that clearly indicate their purpose. Follow the snake_case convention.

Write clear descriptions that explain what the tool does, when to use it, and what it returns. Good descriptions improve model accuracy.

Add descriptions to parameters, such as with Zod’s .describe() method, to provide additional context to the model.

Always validate tool results before passing them back to the model. Handle errors gracefully.

Common Patterns

1. Database Queries

const queryTool = defineTool({
    name: 'query_database',
    description: 'Query the database for records',
    parameters: z.object({
        table: z.enum(['users', 'products', 'orders']),
        filters: z.record(z.unknown()).optional(),
    }),
});

2. API Calls

const apiTool = defineTool({
    name: 'call_api',
    description: 'Make an HTTP API request',
    parameters: z.object({
        endpoint: z.string(),
        method: z.enum(['GET', 'POST', 'PUT', 'DELETE']),
        body: z.record(z.unknown()).optional(),
    }),
});

3. File Operations

const fileTool = defineTool({
    name: 'read_file',
    description: 'Read contents of a file',
    parameters: z.object({
        path: z.string(),
        encoding: z.enum(['utf8', 'base64']).default('utf8'),
    }),
});

Core

Providers

Overview

Function signature

Parameters

Return value

Strict schema enforcement

validateToolCall()

Examples

Basic tool definition

Tool with multiple parameters

Using tools with generate()

Tool execution loop

Complex parameters with nested objects

Tool with enum parameters

Multiple Tools in One Call

Controlling Tool Usage

Type Safety

Best Practices

Common Patterns

1. Database Queries

2. API Calls

3. File Operations

​Overview

​Function signature

​Parameters

​Return value

​Strict schema enforcement

​validateToolCall()

​Examples

​Basic tool definition

​Tool with multiple parameters

​Using tools with generate()

​Tool execution loop

​Complex parameters with nested objects

​Tool with enum parameters

​Multiple Tools in One Call

​Controlling Tool Usage

​Type Safety

​Best Practices

​Common Patterns

​1. Database Queries

​2. API Calls

​3. File Operations

Overview

Function signature

Parameters

Return value

Strict schema enforcement

validateToolCall()

Examples

Basic tool definition

Tool with multiple parameters

Using tools with generate()

Tool execution loop

Complex parameters with nested objects

Tool with enum parameters

Multiple Tools in One Call

Controlling Tool Usage

Type Safety

Best Practices

Common Patterns

1. Database Queries

2. API Calls

3. File Operations