Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

ServerTool.md

247 lines5.2 KB

1---
2id: ServerTool
3title: ServerTool
4---
5​
6# Interface: ServerTool\<TInput, TOutput, TName\>
7​
8Defined in: [activities/chat/tools/tool-definition.ts:12](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L12)
9​
10Marker type for server-side tools
11​
12## Extends
13​
14- [`Tool`](Tool.md)\<`TInput`, `TOutput`, `TName`\>
15​
16## Type Parameters
17​
18### TInput
19​
20`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `z.ZodType`
21​
22### TOutput
23​
24`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `z.ZodType`
25​
26### TName
27​
28`TName` *extends* `string` = `string`
29​
30## Properties
31​
32### \_\_toolSide
33​
34```ts
35__toolSide: "server";
36```
37​
38Defined in: [activities/chat/tools/tool-definition.ts:17](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L17)
39​
40***
41​
42### description
43​
44```ts
45description: string;
46```
47​
48Defined in: [types.ts:340](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L340)
49​
50Clear description of what the tool does.
51​
52This is crucial - the model uses this to decide when to call the tool.
53Be specific about what the tool does, what parameters it needs, and what it returns.
54​
55#### Example
56​
57```ts
58"Get the current weather in a given location. Returns temperature, conditions, and forecast."
59```
60​
61#### Inherited from
62​
63[`Tool`](Tool.md).[`description`](Tool.md#description)
64​
65***
66​
67### execute()?
68​
69```ts
70optional execute: (args) => any;
71```
72​
73Defined in: [types.ts:411](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L411)
74​
75Optional function to execute when the model calls this tool.
76​
77If provided, the SDK will automatically execute the function with the model's arguments
78and feed the result back to the model. This enables autonomous tool use loops.
79​
80Can return any value - will be automatically stringified if needed.
81​
82#### Parameters
83​
84##### args
85​
86`any`
87​
88The arguments parsed from the model's tool call (validated against inputSchema)
89​
90#### Returns
91​
92`any`
93​
94Result to send back to the model (validated against outputSchema if provided)
95​
96#### Example
97​
98```ts
99execute: async (args) => {
100 const weather = await fetchWeather(args.location);
101 return weather; // Can return object or string
103```
104​
105#### Inherited from
106​
107[`Tool`](Tool.md).[`execute`](Tool.md#execute)
108​
109***
110​
111### inputSchema?
112​
113```ts
114optional inputSchema: TInput;
115```
116​
117Defined in: [types.ts:372](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L372)
118​
119Schema describing the tool's input parameters.
120​
121Can be either a Zod schema or a JSON Schema object.
122Defines the structure and types of arguments the tool accepts.
123The model will generate arguments matching this schema.
124Zod schemas are converted to JSON Schema for LLM providers.
125​
126#### See
127​
128 - https://zod.dev/
129 - https://json-schema.org/
130​
131#### Examples
132​
133```ts
134// Using Zod schema
135import { z } from 'zod';
136z.object({
137 location: z.string().describe("City name or coordinates"),
138 unit: z.enum(["celsius", "fahrenheit"]).optional()
139})
140```
141​
142```ts
143// Using JSON Schema
145 type: 'object',
146 properties: {
147 location: { type: 'string', description: 'City name or coordinates' },
148 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
149 },
150 required: ['location']
152```
153​
154#### Inherited from
155​
156[`Tool`](Tool.md).[`inputSchema`](Tool.md#inputschema)
157​
158***
159​
160### metadata?
161​
162```ts
163optional metadata: Record<string, any>;
164```
165​
166Defined in: [types.ts:417](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L417)
167​
168Additional metadata for adapters or custom extensions
169​
170#### Inherited from
171​
172[`Tool`](Tool.md).[`metadata`](Tool.md#metadata)
173​
174***
175​
176### name
177​
178```ts
179name: TName;
180```
181​
182Defined in: [types.ts:330](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L330)
183​
184Unique name of the tool (used by the model to call it).
185​
186Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
187Must be unique within the tools array.
188​
189#### Example
190​
191```ts
192"get_weather", "search_database", "sendEmail"
193```
194​
195#### Inherited from
196​
197[`Tool`](Tool.md).[`name`](Tool.md#name)
198​
199***
200​
201### needsApproval?
202​
203```ts
204optional needsApproval: boolean;
205```
206​
207Defined in: [types.ts:414](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L414)
208​
209If true, tool execution requires user approval before running. Works with both server and client tools.
210​
211#### Inherited from
212​
213[`Tool`](Tool.md).[`needsApproval`](Tool.md#needsapproval)
214​
215***
216​
217### outputSchema?
218​
219```ts
220optional outputSchema: TOutput;
221```
222​
223Defined in: [types.ts:392](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L392)
224​
225Optional schema for validating tool output.
226​
227Can be either a Zod schema or a JSON Schema object.
228If provided with a Zod schema, tool results will be validated against this schema before
229being sent back to the model. This catches bugs in tool implementations
230and ensures consistent output formatting.
231​
232Note: This is client-side validation only - not sent to LLM providers.
233Note: JSON Schema output validation is not performed at runtime.
234​
235#### Example
236​
237```ts
238z.object({
239 temperature: z.number(),
240 conditions: z.string(),
241 forecast: z.array(z.string()).optional()
242})
243```
244​
245#### Inherited from
246​
247[`Tool`](Tool.md).[`outputSchema`](Tool.md#outputschema)