Open History to see the last commit
1---
2id: ServerTool
3title: ServerTool
4---
5
6# Interface: ServerTool\<TInput, TOutput, TName\>
7
8Defined in: [packages/typescript/ai/src/activities/chat/tools/tool-definition.ts:13](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L13)
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) = [`SchemaInput`](../type-aliases/SchemaInput.md)
21
22### TOutput
23
24`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = [`SchemaInput`](../type-aliases/SchemaInput.md)
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: [packages/typescript/ai/src/activities/chat/tools/tool-definition.ts:18](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/activities/chat/tools/tool-definition.ts#L18)
39
40***
41
42### description
43
44```ts
45description: string;
46```
47
48Defined in: [packages/typescript/ai/src/types.ts:509](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L509)
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, context?) => any;
71```
72
73Defined in: [packages/typescript/ai/src/types.ts:589](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L589)
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##### context?
91
92[`ToolExecutionContext`](ToolExecutionContext.md)
93
94#### Returns
95
96`any`
97
98Result to send back to the model (validated against outputSchema if provided)
99
100#### Example
101
102```ts
103execute: async (args) => {
104 const weather = await fetchWeather(args.location);
105 return weather; // Can return object or string
106}
107```
108
109#### Inherited from
110
111[`Tool`](Tool.md).[`execute`](Tool.md#execute)
112
113***
114
115### inputSchema?
116
117```ts
118optional inputSchema: TInput;
119```
120
121Defined in: [packages/typescript/ai/src/types.ts:549](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L549)
122
123Schema describing the tool's input parameters.
124
125Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object.
126Defines the structure and types of arguments the tool accepts.
127The model will generate arguments matching this schema.
128Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.
129
130#### See
131
132 - https://standardschema.dev/json-schema
133 - https://json-schema.org/
134
135#### Examples
136
137```ts
138// Using Zod v4+ schema (natively supports Standard JSON Schema)
139import { z } from 'zod';
140z.object({
141 location: z.string().describe("City name or coordinates"),
142 unit: z.enum(["celsius", "fahrenheit"]).optional()
143})
144```
145
146```ts
147// Using ArkType (natively supports Standard JSON Schema)
148import { type } from 'arktype';
149type({
150 location: 'string',
151 unit: "'celsius' | 'fahrenheit'"
152})
153```
154
155```ts
156// Using plain JSON Schema
157{
158 type: 'object',
159 properties: {
160 location: { type: 'string', description: 'City name or coordinates' },
161 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
162 },
163 required: ['location']
164}
165```
166
167#### Inherited from
168
169[`Tool`](Tool.md).[`inputSchema`](Tool.md#inputschema)
170
171***
172
173### lazy?
174
175```ts
176optional lazy: boolean;
177```
178
179Defined in: [packages/typescript/ai/src/types.ts:597](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L597)
180
181If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Only meaningful when used with chat().
182
183#### Inherited from
184
185[`Tool`](Tool.md).[`lazy`](Tool.md#lazy)
186
187***
188
189### metadata?
190
191```ts
192optional metadata: Record<string, any>;
193```
194
195Defined in: [packages/typescript/ai/src/types.ts:600](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L600)
196
197Additional metadata for adapters or custom extensions
198
199#### Inherited from
200
201[`Tool`](Tool.md).[`metadata`](Tool.md#metadata)
202
203***
204
205### name
206
207```ts
208name: TName;
209```
210
211Defined in: [packages/typescript/ai/src/types.ts:499](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L499)
212
213Unique name of the tool (used by the model to call it).
214
215Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
216Must be unique within the tools array.
217
218#### Example
219
220```ts
221"get_weather", "search_database", "sendEmail"
222```
223
224#### Inherited from
225
226[`Tool`](Tool.md).[`name`](Tool.md#name)
227
228***
229
230### needsApproval?
231
232```ts
233optional needsApproval: boolean;
234```
235
236Defined in: [packages/typescript/ai/src/types.ts:594](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L594)
237
238If true, tool execution requires user approval before running. Works with both server and client tools.
239
240#### Inherited from
241
242[`Tool`](Tool.md).[`needsApproval`](Tool.md#needsapproval)
243
244***
245
246### outputSchema?
247
248```ts
249optional outputSchema: TOutput;
250```
251
252Defined in: [packages/typescript/ai/src/types.ts:570](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L570)
253
254Optional schema for validating tool output.
255
256Can be any Standard JSON Schema compliant schema or a plain JSON Schema object.
257If provided with a Standard Schema compliant schema, tool results will be validated
258against this schema before being sent back to the model. This catches bugs in tool
259implementations and ensures consistent output formatting.
260
261Note: This is client-side validation only - not sent to LLM providers.
262Note: Plain JSON Schema output validation is not performed at runtime.
263
264#### Example
265
266```ts
267// Using Zod
268z.object({
269 temperature: z.number(),
270 conditions: z.string(),
271 forecast: z.array(z.string()).optional()
272})
273```
274
275#### Inherited from
276
277[`Tool`](Tool.md).[`outputSchema`](Tool.md#outputschema)