Interface: ToolDefinition<TInput, TOutput, TName>#
Defined in: activities/chat/tools/tool-definition.ts:104
Tool definition builder that allows creating server or client tools from a shared definition
Extends#
ToolDefinitionInstance<TInput,TOutput,TName>
Type Parameters#
TInput#
TInput extends SchemaInput = z.ZodType
TOutput#
TOutput extends SchemaInput = z.ZodType
TName#
TName extends string = string
Properties#
__toolSide#
__toolSide: "definition";
Defined in: activities/chat/tools/tool-definition.ts:48
Inherited from#
ToolDefinitionInstance.__toolSide
client()#
client: (execute?) => ClientTool<TInput, TOutput, TName>;
Defined in: activities/chat/tools/tool-definition.ts:121
Create a client-side tool with optional execute function
Parameters#
execute?#
(args) =>
| InferSchemaType<TOutput>
| Promise<InferSchemaType<TOutput>>
Returns#
ClientTool<TInput, TOutput, TName>
description#
description: string;
Defined in: types.ts:340
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#
"Get the current weather in a given location. Returns temperature, conditions, and forecast."
Inherited from#
ToolDefinitionInstance.description
execute()?#
optional execute: (args) => any;
Defined in: types.ts:411
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#
execute: async (args) => {
const weather = await fetchWeather(args.location);
return weather; // Can return object or string
}
Inherited from#
ToolDefinitionInstance.execute
inputSchema?#
optional inputSchema: TInput;
Defined in: types.ts:372
Schema describing the tool's input parameters.
Can be either a Zod schema or a JSON Schema object. Defines the structure and types of arguments the tool accepts. The model will generate arguments matching this schema. Zod schemas are converted to JSON Schema for LLM providers.
See#
Examples#
// Using Zod schema
import { z } from 'zod';
z.object({
location: z.string().describe("City name or coordinates"),
unit: z.enum(["celsius", "fahrenheit"]).optional()
})
// Using JSON Schema
{
type: 'object',
properties: {
location: { type: 'string', description: 'City name or coordinates' },
unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
},
required: ['location']
}
Inherited from#
ToolDefinitionInstance.inputSchema
metadata?#
optional metadata: Record<string, any>;
Defined in: types.ts:417
Additional metadata for adapters or custom extensions
Inherited from#
ToolDefinitionInstance.metadata
name#
name: TName;
Defined in: types.ts:330
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#
"get_weather", "search_database", "sendEmail"
Inherited from#
needsApproval?#
optional needsApproval: boolean;
Defined in: types.ts:414
If true, tool execution requires user approval before running. Works with both server and client tools.
Inherited from#
ToolDefinitionInstance.needsApproval
outputSchema?#
optional outputSchema: TOutput;
Defined in: types.ts:392
Optional schema for validating tool output.
Can be either a Zod schema or a JSON Schema object. If provided with a Zod 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: JSON Schema output validation is not performed at runtime.
Example#
z.object({
temperature: z.number(),
conditions: z.string(),
forecast: z.array(z.string()).optional()
})
Inherited from#
ToolDefinitionInstance.outputSchema
server()#
server: (execute) => ServerTool<TInput, TOutput, TName>;
Defined in: activities/chat/tools/tool-definition.ts:112
Create a server-side tool with execute function
Parameters#
execute#
(args) =>
| InferSchemaType<TOutput>
| Promise<InferSchemaType<TOutput>>
Returns#
ServerTool<TInput, TOutput, TName>