TanStack
AI v0v0
Documentation
Framework
Version
Menu
Getting Started
Guides
API
Adapters
Community Adapters
Class References
Function References
Interface References
Type Alias References
Variable References
Learn about TanStack AdsHide Ads

ToolDefinitionInstance

Interface: ToolDefinitionInstance<TInput, TOutput, TName>

Defined in: activities/chat/tools/tool-definition.ts:43

Tool definition that can be used directly or instantiated for server/client

Extends
  • Tool<TInput, TOutput, TName>

Extended by

Type Parameters

TInput

TInput extends SchemaInput = SchemaInput

TOutput

TOutput extends SchemaInput = SchemaInput

TName

TName extends string = string

Properties

__toolSide
ts
__toolSide: "definition";

__toolSide: "definition";

Defined in: activities/chat/tools/tool-definition.ts:48

description
ts
description: string;

description: string;

Defined in: types.ts:351

Clear description of what the tool does.

This is crucial - the model uses this to decide when to call the tool. Be specific about what the tool does, what parameters it needs, and what it returns.

Example
ts
"Get the current weather in a given location. Returns temperature, conditions, and forecast."

"Get the current weather in a given location. Returns temperature, conditions, and forecast."

Inherited from

Tool.description

execute()?
ts
optional execute: (args) => any;

optional execute: (args) => any;

Defined in: types.ts:431

Optional function to execute when the model calls this tool.

If provided, the SDK will automatically execute the function with the model's arguments and feed the result back to the model. This enables autonomous tool use loops.

Can return any value - will be automatically stringified if needed.

Parameters
args

any

The arguments parsed from the model's tool call (validated against inputSchema)

Returns

any

Result to send back to the model (validated against outputSchema if provided)

Example
ts
execute: async (args) => {
  const weather = await fetchWeather(args.location);
  return weather; // Can return object or string
}

execute: async (args) => {
  const weather = await fetchWeather(args.location);
  return weather; // Can return object or string
}

Inherited from

Tool.execute

inputSchema?
ts
optional inputSchema: TInput;

optional inputSchema: TInput;

Defined in: types.ts:391

Schema describing the tool's input parameters.

Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object. Defines the structure and types of arguments the tool accepts. The model will generate arguments matching this schema. Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.

See

Examples
ts
// Using Zod v4+ schema (natively supports Standard JSON Schema)
import { z } from 'zod';
z.object({
  location: z.string().describe("City name or coordinates"),
  unit: z.enum(["celsius", "fahrenheit"]).optional()
})

// Using Zod v4+ schema (natively supports Standard JSON Schema)
import { z } from 'zod';
z.object({
  location: z.string().describe("City name or coordinates"),
  unit: z.enum(["celsius", "fahrenheit"]).optional()
})
ts
// Using ArkType (natively supports Standard JSON Schema)
import { type } from 'arktype';
type({
  location: 'string',
  unit: "'celsius' | 'fahrenheit'"
})

// Using ArkType (natively supports Standard JSON Schema)
import { type } from 'arktype';
type({
  location: 'string',
  unit: "'celsius' | 'fahrenheit'"
})
ts
// Using plain JSON Schema
{
  type: 'object',
  properties: {
    location: { type: 'string', description: 'City name or coordinates' },
    unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
  },
  required: ['location']
}

// Using plain JSON Schema
{
  type: 'object',
  properties: {
    location: { type: 'string', description: 'City name or coordinates' },
    unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
  },
  required: ['location']
}

Inherited from

Tool.inputSchema

metadata?
ts
optional metadata: Record<string, any>;

optional metadata: Record<string, any>;

Defined in: types.ts:437

Additional metadata for adapters or custom extensions

Inherited from

Tool.metadata

name
ts
name: TName;

name: TName;

Defined in: types.ts:341

Unique name of the tool (used by the model to call it).

Should be descriptive and follow naming conventions (e.g., snake_case or camelCase). Must be unique within the tools array.

Example
ts
"get_weather", "search_database", "sendEmail"

"get_weather", "search_database", "sendEmail"

Inherited from

Tool.name

needsApproval?
ts
optional needsApproval: boolean;

optional needsApproval: boolean;

Defined in: types.ts:434

If true, tool execution requires user approval before running. Works with both server and client tools.

Inherited from

Tool.needsApproval

outputSchema?
ts
optional outputSchema: TOutput;

optional outputSchema: TOutput;

Defined in: types.ts:412

Optional schema for validating tool output.

Can be any Standard JSON Schema compliant schema or a plain JSON Schema object. If provided with a Standard Schema compliant schema, tool results will be validated against this schema before being sent back to the model. This catches bugs in tool implementations and ensures consistent output formatting.

Note: This is client-side validation only - not sent to LLM providers. Note: Plain JSON Schema output validation is not performed at runtime.

Example
ts
// Using Zod
z.object({
  temperature: z.number(),
  conditions: z.string(),
  forecast: z.array(z.string()).optional()
})

// Using Zod
z.object({
  temperature: z.number(),
  conditions: z.string(),
  forecast: z.array(z.string()).optional()
})

Inherited from

Tool.outputSchema

Edit on GitHub
Learn about TanStack AdsHide Ads
ToolDefinitionConfig
ToolInputAvailableStreamChunk
PartnersBecome a Partner
Code Rabbit
Cloudflare
AG Grid
Netlify
Neon
WorkOS
Clerk
Convex
Electric
Sentry
Prisma
Strapi
Unkey
Learn about TanStack AdsHide Ads