Tool Calling

Tool calling enables language models to interact with external functions and APIs, extending their capabilities beyond text generation.

Define a Tool

Create tools using defineTool(). parameters takes a Standard Schema with JSON Schema support, such as a Zod 4.2+ schema, or plain JSON Schema. See Schemas for the supported libraries.

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

const weatherTool = defineTool({
    name: 'get_weather',
    description: 'Get mocked weather information for a city',
    parameters: z.object({
        location: z.string().describe('City name'),
        unit: z.enum(['celsius', 'fahrenheit']),
    }),
});

Strict tool schemas

Set strict: true on a tool to make the provider enforce the tool’s parameter schema during argument generation. Strictness is a per-tool opt-in: omitting strict or setting strict: false keeps that tool non-strict on every provider.

const lookupOrder = defineTool({
    name: 'lookup_order',
    description: 'Look up an order by id',
    strict: true,
    parameters: z.object({
        orderId: z.string(),
        note: z.string().nullable().describe('Extra note, or null'),
    }),
});

Strict-capable schema contract

A strict tool’s schema must fit the strict-capable subset that schema-enforcing providers accept. Core-ai validates strict tools against this contract locally, before any API call, and reports every violation with a fix hint. Non-strict tools are never validated against it. The contract applies to the tool’s JSON Schema, so it covers Standard Schemas and plain JSON Schema alike. The examples below use Zod; other libraries produce the equivalent JSON Schema keywords.

Closed objects whose keys the provider can require. A key must be required, accept null (.nullable()), or declare a default (.default()), so the model can always send a value for it. Use .nullable() for values the model may leave out: a key that is only .optional() is rejected.
Object root. parameters must describe an object, such as a z.object(); a primitive, array, or union at the root is rejected.
Allowed keywords — the intersection of what OpenAI and Anthropic accept in strict mode, not the union: $ref / $defs, type (object, array, string, number, integer, boolean, null), properties, required, additionalProperties: false, items, enum, const, unions (anyOf from z.union(), and oneOf from z.discriminatedUnion(), which providers receive as anyOf), format (date-time, time, date, duration, email, hostname, ipv4, ipv6, uuid), pattern, title, description, default, examples.
Rejected: numeric bounds (minimum, maximum, multipleOf — Zod’s implicit safe-integer bounds on z.int() are exempt and stripped), string and array length constraints (minLength, maxLength, minItems, maxItems), URL formats (z.url() emits format: "uri", which OpenAI does not accept — use z.string()), intersections (z.intersection() / .and() emit allOf — flatten into one z.object()), tuples (prefixItems), not, open objects (z.record(), .catchall(), .passthrough(), z.looseObject()), and recursive schemas (z.lazy()).

Check constraints you remove from the schema (ranges, lengths) in your tool implementation.

Check model support

model.capabilities.tools.strictSchemas reports whether the selected model supports strict tools and any provider limit:

import { createOpenAI } from '@core-ai/openai';

const model = createOpenAI().chatModel('gpt-5-mini');
const strictSchemas = model.capabilities.tools.strictSchemas;

if (strictSchemas.supported) {
    console.log(strictSchemas.maxStrictTools); // provider limits, if any
    console.log(strictSchemas.maxUnionParameters);
}

Unknown and future model IDs resolve optimistically to { supported: true }: core-ai forwards the explicit strict: true and lets the provider reject the request if the model genuinely lacks support. This keeps newly released models usable without a registry update. Fine-tuned OpenAI ft:<base>:... models inherit their base model’s capabilities instead.

Errors

Invalid strict configuration throws ToolSchemaStrictnessError before the provider request. Its reason is one of:

'unsupported' — the model is known not to support strict tool schemas.
'limit-exceeded' — the request contains more strict tools than the provider’s maxStrictTools limit.
'union-limit-exceeded' — the request’s strict tools have more union-typed parameters than the provider’s maxUnionParameters limit. A union-typed parameter is a property whose schema is an anyOf, a oneOf, or a type array with more than one entry, including every nullable key.
'invalid-schema' — a strict tool’s schema is outside the strict-capable contract. The error carries a violations array naming each offending schema path:

openai model "gpt-5-mini" received strict tools whose schemas are outside the
strict-capable schema contract: tool "search" at properties.limit.maximum:
remove numeric bounds (.max()/.lt()/.lte()) — numeric range constraints are
outside the strict-capable subset; validate ranges after parsing instead

Parallel tool calls

OpenAI does not guarantee schema adherence when parallel tool calls are enabled. Core-ai does not change that setting for you: when you combine strict tools with providerOptions.openai.parallelToolCalls: true, set it to false yourself if you need guaranteed adherence.

Provider support

Provider	Strict tool schemas
Anthropic	Yes, on Claude 4.5 and later models; at most 20 strict tools and 16 union-typed parameters per request
Anthropic Vertex	Yes; requires the `structured_outputs` partner-model feature in your organization policy — see Anthropic Vertex
OpenAI	Yes
Azure OpenAI	Yes; classic deployments need `api-version` `2024-08-01-preview` or later
Kimi	Yes
OpenAI Compat	Yes, when the endpoint implements OpenAI strict function tools
Omnifact	Yes
Google GenAI / Google Vertex	No; `strict: true` throws locally
Mistral	No; `strict: true` throws locally

On the OpenAI family (openai, azure-openai, kimi, openai-compat, omnifact), strict tools are sent with strict: true and a normalized schema ($schema stripped, additionalProperties: false added recursively, oneOf rewritten to anyOf, and nullable or defaulted keys listed in required — all semantics-preserving). Non-strict tools are sent with the tool’s JSON Schema unchanged. On the Responses API they carry an explicit strict: false, because that API otherwise tries to normalize tools into strict mode on its own; on Chat Completions, which is non-strict by default, the field is omitted. Anthropic follows the same split: strict tools get the provider’s normalization (which also drops the numeric and length constraints its strict grammar rejects), non-strict tools are sent raw. Anthropic also rejects a single strict schema it finds too complex (“Schema is too complex”; 30 plain required keys in one tool exceed it) with a provider error. core-ai cannot check that limit because Anthropic does not publish it.

Strict generation reduces invalid arguments but does not make tool execution trusted. Check each call with validateToolCall(), or validate ToolCall.arguments yourself for plain JSON Schema tools, before executing code or making external requests. See Validate tool calls.

Strict tool schemas apply to function arguments during generate() and stream(). They are separate from the structured response formats used by generateObject() and streamObject(). A provider can support one without supporting the other.

Basic Tool Usage

Implement a complete tool calling flow:

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

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const model = openai.chatModel('gpt-5-mini');

// Define the tool
const weatherParameters = z.object({
    location: z.string().describe('City name'),
    unit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
});

const weatherTool = defineTool({
    name: 'get_weather',
    description: 'Get mocked weather information for a city',
    parameters: weatherParameters,
});

// Implement the tool function
function runWeatherTool(args: z.output<typeof weatherParameters>): string {
    const conditions = ['sunny', 'cloudy', 'windy'];
    const condition = conditions[args.location.length % conditions.length];
    const temperature = 10 + (args.location.length % 18);

    return JSON.stringify({
        location: args.location,
        unit: args.unit,
        temperature,
        condition,
    });
}

// Initial request with tools
const initialMessages = [
    {
        role: 'user' as const,
        content: 'What is the weather in Berlin? Reply in one sentence.',
    },
];

const firstResult = await generate({
    model,
    messages: initialMessages,
    tools: { get_weather: weatherTool },
    toolChoice: 'auto',
});

// Check if model wants to call tools
if (firstResult.finishReason !== 'tool-calls') {
    console.log('Model response without tool calls:', firstResult.content);
    process.exit(0);
}

// Execute the tool calls
const toolMessages = await Promise.all(
    firstResult.toolCalls.map(async (call) => {
        if (call.name !== weatherTool.name) {
            return {
                role: 'tool' as const,
                toolCallId: call.id,
                content: JSON.stringify({
                    error: `Unknown tool: ${call.name}`,
                }),
                isError: true,
            };
        }

        // Validate the arguments against weatherParameters
        const validation = await validateToolCall(weatherTool, call);
        if (validation.issues) {
            return {
                role: 'tool' as const,
                toolCallId: call.id,
                content: JSON.stringify({
                    error: 'Invalid arguments',
                    issues: validation.issues,
                }),
                isError: true,
            };
        }

        return {
            role: 'tool' as const,
            toolCallId: call.id,
            content: runWeatherTool(validation.value),
        };
    })
);

// Get final response with tool results
const secondResult = await generate({
    model,
    messages: [
        ...initialMessages,
        resultToMessage(firstResult),
        ...toolMessages,
    ],
    tools: { get_weather: weatherTool },
});

console.log('Final response:', secondResult.content);

Tool Choice Strategies

Control when and how tools are used:

// Let model decide whether to use tools
const result = await generate({
    model,
    messages,
    tools: { get_weather: weatherTool },
    toolChoice: 'auto', // Default behavior
});

// Force model to use at least one tool
const result = await generate({
    model,
    messages,
    tools: { get_weather: weatherTool },
    toolChoice: 'required',
});

// Disable tool usage
const result = await generate({
    model,
    messages,
    tools: { get_weather: weatherTool },
    toolChoice: 'none',
});

// Force a specific tool
const result = await generate({
    model,
    messages,
    tools: { get_weather: weatherTool },
    toolChoice: { type: 'tool', toolName: 'get_weather' },
});

Multiple Tools

Provide multiple tools for the model to choose from:

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

const weatherTool = defineTool({
    name: 'get_weather',
    description: 'Get current weather information',
    parameters: z.object({
        location: z.string(),
    }),
});

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

const searchTool = defineTool({
    name: 'search_web',
    description: 'Search the web for information',
    parameters: z.object({
        query: z.string(),
        limit: z.number().default(10),
    }),
});

const result = await generate({
    model,
    messages: [
        {
            role: 'user',
            content: 'What is the weather in London and what time is it there?',
        },
    ],
    tools: {
        get_weather: weatherTool,
        get_time: timeTool,
        search_web: searchTool,
    },
    toolChoice: 'auto',
});

// Model may call multiple tools
if (result.finishReason === 'tool-calls') {
    console.log('Tools called:', result.toolCalls.length);
    result.toolCalls.forEach((call) => {
        console.log(`- ${call.name}:`, call.arguments);
    });
}

Validate tool calls

Tool arguments come from the model, so validate them before you execute anything, whether the tool is strict or not. How you validate depends on the tool’s parameters:

Standard Schema: pass the tool and the call to validateToolCall(). It returns { value }, the schema’s output typed as such, or { issues }, listing each problem with a message and an optional path. Invalid arguments are reported, never thrown. So is a validator that throws, such as a transform calling new URL(): its error message becomes the only issue.
Plain JSON Schema: core-ai sends the schema as is and has no validator for it, so validateToolCall() returns undefined. Validate ToolCall.arguments yourself.

if (call.name === weatherTool.name) {
    const validation = await validateToolCall(weatherTool, call);
    if (validation.issues) {
        // Send the issues back to the model as an error tool result
    } else {
        // Typed as z.output<typeof weatherParameters>
        runWeatherTool(validation.value);
    }
}

Check call.name first: validateToolCall() throws a ValidationError for a call to another tool. value has the schema’s defaults and transforms applied, while ToolCall.arguments keeps the arguments exactly as the model sent them. See Handling tool calls for a complete loop.

JSON Schema tools

Use plain JSON Schema for tools whose schemas you receive at runtime, such as tools listed by an MCP server:

import { defineTool, type JsonSchema, type ToolSet } from '@core-ai/core-ai';

type McpTool = {
    name: string;
    description?: string;
    inputSchema: JsonSchema;
};

function toToolSet(mcpTools: McpTool[]): ToolSet {
    return Object.fromEntries(
        mcpTools.map((tool) => [
            tool.name,
            defineTool({
                name: tool.name,
                description: tool.description ?? '',
                parameters: tool.inputSchema,
            }),
        ])
    );
}

validateToolCall() returns undefined for these tools. Validate their arguments with a JSON Schema validator, or let the MCP server reject invalid input. To validate them with validateToolCall(), wrap your validator in the Standard Schema interface:

import type { JsonSchema, StandardSchemaWithJson } from '@core-ai/core-ai';

function withValidator(
    jsonSchema: JsonSchema,
    // Returns one message per problem, or none when the value is valid
    check: (value: unknown) => string[]
): StandardSchemaWithJson {
    return {
        '~standard': {
            version: 1,
            vendor: 'my-app',
            validate: (value) => {
                const messages = check(value);
                return messages.length === 0
                    ? { value }
                    : { issues: messages.map((message) => ({ message })) };
            },
            jsonSchema: {
                input: () => jsonSchema,
                output: () => jsonSchema,
            },
        },
    };
}

Handling Tool Calls

Execute validated tool calls the same way for strict and non-strict tools. Send validation issues back as an error tool result so the model can correct its call:

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

const weatherParameters = z.object({
    location: z.string(),
    unit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
});

const weatherTool = defineTool({
    name: 'get_weather',
    description: 'Get weather information',
    parameters: weatherParameters,
});

type WeatherArgs = z.infer<typeof weatherParameters>;

function getWeather(args: WeatherArgs): string {
    // Implement your weather API call here
    return JSON.stringify({ temperature: 20, condition: 'sunny' });
}

const result = await generate({
    model,
    messages: [{ role: 'user', content: 'Weather in Paris?' }],
    tools: { get_weather: weatherTool },
});

if (result.finishReason === 'tool-calls') {
    const toolMessages = await Promise.all(
        result.toolCalls.map(async (call) => {
            if (call.name !== weatherTool.name) {
                return {
                    role: 'tool' as const,
                    toolCallId: call.id,
                    content: JSON.stringify({
                        error: `Unknown tool: ${call.name}`,
                    }),
                    isError: true,
                };
            }

            // Report invalid arguments back to the model
            const validation = await validateToolCall(weatherTool, call);
            if (validation.issues) {
                return {
                    role: 'tool' as const,
                    toolCallId: call.id,
                    content: JSON.stringify({
                        error: 'Invalid arguments',
                        issues: validation.issues,
                    }),
                    isError: true,
                };
            }

            // Execute tool with the schema's output; the default unit is applied
            try {
                return {
                    role: 'tool' as const,
                    toolCallId: call.id,
                    content: getWeather(validation.value),
                };
            } catch (error) {
                return {
                    role: 'tool' as const,
                    toolCallId: call.id,
                    content: JSON.stringify({ error: String(error) }),
                    isError: true,
                };
            }
        })
    );

    // Continue conversation with tool results
    const finalResult = await generate({
        model,
        messages: [
            { role: 'user', content: 'Weather in Paris?' },
            resultToMessage(result),
            ...toolMessages,
        ],
        tools: { get_weather: weatherTool },
    });

    console.log(finalResult.content);
}

Tool discovery

For large tool sets, such as the tools of several MCP servers, declare a few tools up front and let the model discover the rest with toolDiscovery. See Tool Discovery. With discovery enabled, finishReason: 'tool-calls' also covers pending discovery calls, which arrive in result.discoveryCalls and never in toolCalls. Loop while finishReason is 'tool-calls' and answer both toolCalls and discoveryCalls: a step can contain only discovery calls.

Tool Calling with Streaming

Handle tool calls during streaming:

import { stream, defineTool } from '@core-ai/core-ai';
import type { ToolCall } from '@core-ai/core-ai';
import { z } from 'zod';

const calculatorTool = defineTool({
    name: 'calculate',
    description: 'Perform a calculation',
    parameters: z.object({
        expression: z.string().describe('Mathematical expression'),
    }),
});

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

const toolCalls: ToolCall[] = [];

for await (const event of result) {
    switch (event.type) {
        case 'text-delta':
            process.stdout.write(event.text);
            break;

        case 'tool-call-start':
            console.log(`\nCalling tool: ${event.toolName}`);
            break;

        case 'tool-call-delta':
            // Tool arguments are being streamed
            process.stdout.write(event.argumentsDelta);
            break;

        case 'tool-call-end':
            console.log(`\nTool call complete:`, event.toolCall);
            toolCalls.push(event.toolCall);
            break;
    }
}

const response = await result.result;

if (response.finishReason === 'tool-calls') {
    console.log('Need to execute tools:', toolCalls);
}

Advanced Tool Examples

Database Query
API Call
File Operations

const queryTool = defineTool({
  name: 'query_database',
  description: 'Query the user database',
  parameters: z.object({
    query: z.string().describe('SQL query to execute'),
    limit: z.number().max(100).default(10),
  }),
});

function executeQuery(args: { query: string; limit: number }) {
  // Validate and execute safe queries only
  if (!args.query.toLowerCase().startsWith('select')) {
    throw new Error('Only SELECT queries are allowed');
  }

  // Execute query with your database client
  const results = db.query(args.query, { limit: args.limit });
  return JSON.stringify(results);
}

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

async function callApi(args: {
  endpoint: string;
  method: string;
  body?: Record<string, unknown>;
}) {
  const response = await fetch(args.endpoint, {
    method: args.method,
    headers: { 'Content-Type': 'application/json' },
    body: args.body ? JSON.stringify(args.body) : undefined,
  });

  return JSON.stringify(await response.json());
}

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

async function readFile(args: { path: string; encoding: string }) {
  // Validate path is safe
  if (args.path.includes('..')) {
    throw new Error('Path traversal not allowed');
  }

  const content = await fs.readFile(args.path, args.encoding as any);
  return JSON.stringify({ content });
}

Tool Result Messages

Structure tool results properly:

import type { ToolResultMessage } from '@core-ai/core-ai';

// Success case
const successMessage: ToolResultMessage = {
    role: 'tool',
    toolCallId: call.id,
    content: JSON.stringify({
        result: 'success',
        data: {
            /* ... */
        },
    }),
};

// Error case
const errorMessage: ToolResultMessage = {
    role: 'tool',
    toolCallId: call.id,
    content: JSON.stringify({ error: 'Something went wrong' }),
    isError: true, // Mark as error
};

Helper: Convert Result to Message

Use resultToMessage() to simplify conversation building:

import { generate, resultToMessage } from '@core-ai/core-ai';

const messages = [{ role: 'user', content: 'What is the weather?' }];

const firstResult = await generate({
    model,
    messages,
    tools: { get_weather: weatherTool },
});

// Convert result to assistant message automatically
const assistantMessage = resultToMessage(firstResult);

messages.push(assistantMessage);

// Add tool results
if (firstResult.finishReason === 'tool-calls') {
    const toolResults = executeTools(firstResult.toolCalls);
    messages.push(...toolResults);

    const secondResult = await generate({ model, messages, tools });
    console.log(secondResult.content);
}

Best Practices

Validate tool arguments before execution

Check calls to Standard Schema tools with validateToolCall(), and validate call.arguments yourself for plain JSON Schema tools:

const validation = await validateToolCall(tool, call);

if (validation === undefined) {
  // Plain JSON Schema tool: validate call.arguments yourself
} else if (validation.issues) {
  return {
    role: 'tool',
    toolCallId: call.id,
    content: JSON.stringify({ issues: validation.issues }),
    isError: true,
  };
} else {
  // Use the schema's output, not the raw arguments
  const result = executeTool(validation.value);
}

Add detailed tool descriptions

Help the model understand when to use tools:

const tool = defineTool({
  name: 'get_weather',
  description: 'Get current weather information for a specific location. Use this when users ask about weather, temperature, or conditions.',
  parameters: z.object({
    location: z.string().describe('City name or location. Examples: "London", "New York, NY", "Tokyo, Japan"'),
  }),
});

Handle errors gracefully

Return errors as tool results instead of throwing:

try {
  const result = await executeToolFunction(args);
  return {
    role: 'tool',
    toolCallId: call.id,
    content: JSON.stringify(result),
  };
} catch (error) {
  return {
    role: 'tool',
    toolCallId: call.id,
    content: JSON.stringify({
      error: error.message,
      type: error.name,
    }),
    isError: true,
  };
}

Limit tool execution time

Prevent tools from hanging:

async function executeToolWithTimeout(
  tool: () => Promise<string>,
  timeoutMs: number = 5000
): Promise<string> {
  const timeoutPromise = new Promise<never>((_, reject) =>
    setTimeout(() => reject(new Error('Tool timeout')), timeoutMs)
  );

  return Promise.race([tool(), timeoutPromise]);
}

Next Steps

Chat Completion

Learn basic message generation

Structured Outputs

Combine tools with structured responses

Streaming

Stream tool calls in real-time

Tool Discovery

Let the model discover tools on demand

Get Started

Core Concepts

Guides

Observability

Examples

Define a Tool

Strict tool schemas

Strict-capable schema contract

Check model support

Errors

Parallel tool calls

Provider support

Basic Tool Usage

Tool Choice Strategies

Multiple Tools

Validate tool calls

JSON Schema tools

Handling Tool Calls

Tool discovery

Tool Calling with Streaming

Advanced Tool Examples

Tool Result Messages

Helper: Convert Result to Message

Best Practices

Next Steps

Chat Completion

Structured Outputs

Streaming

Tool Discovery

​Define a Tool

​Strict tool schemas

​Strict-capable schema contract

​Check model support

​Errors

​Parallel tool calls

​Provider support

​Basic Tool Usage

​Tool Choice Strategies

​Multiple Tools

​Validate tool calls

​JSON Schema tools

​Handling Tool Calls

​Tool discovery

​Tool Calling with Streaming

​Advanced Tool Examples

​Tool Result Messages

​Helper: Convert Result to Message

​Best Practices

​Next Steps

Chat Completion

Structured Outputs

Streaming

Tool Discovery

Define a Tool

Strict tool schemas

Strict-capable schema contract

Check model support

Errors

Parallel tool calls

Provider support

Basic Tool Usage

Tool Choice Strategies

Multiple Tools

Validate tool calls

JSON Schema tools

Handling Tool Calls

Tool discovery

Tool Calling with Streaming

Advanced Tool Examples

Tool Result Messages

Helper: Convert Result to Message

Best Practices

Next Steps