Open History to see the last commit
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
102}
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
144{
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']
151}
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)