Open History to see the last commit
1---
2id: ServerTool
3title: ServerTool
4---
5
6# Interface: ServerTool\<TInput, TOutput, TName, TContext\>
7
8Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:12](https://github.com/TanStack/ai/blob/main/packages/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`, `TContext`\>
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### TContext
31
32`TContext` = `unknown`
33
34## Properties
35
36### \_\_toolSide
37
38```ts
39__toolSide: "server";
40```
41
42Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:18](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/tools/tool-definition.ts#L18)
43
44***
45
46### description
47
48```ts
49description: string;
50```
51
52Defined in: [packages/ai/src/types.ts:622](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L622)
53
54Clear description of what the tool does.
55
56This is crucial - the model uses this to decide when to call the tool.
57Be specific about what the tool does, what parameters it needs, and what it returns.
58
59#### Example
60
61```ts
62"Get the current weather in a given location. Returns temperature, conditions, and forecast."
63```
64
65#### Inherited from
66
67[`Tool`](Tool.md).[`description`](Tool.md#description)
68
69***
70
71### execute?
72
73```ts
74optional execute: ToolExecuteFunction<TInput, TOutput, TContext>;
75```
76
77Defined in: [packages/ai/src/types.ts:702](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L702)
78
79Optional function to execute when the model calls this tool.
80
81If provided, the SDK will automatically execute the function with the model's arguments
82and feed the result back to the model. This enables autonomous tool use loops.
83
84Can return any value - will be automatically stringified if needed.
85
86#### Param
87
88The arguments parsed from the model's tool call (validated against inputSchema)
89
90#### Returns
91
92Result to send back to the model (validated against outputSchema if provided)
93
94#### Example
95
96```ts
97execute: async (args) => {
98 const weather = await fetchWeather(args.location);
99 return weather; // Can return object or string
100}
101```
102
103#### Inherited from
104
105[`Tool`](Tool.md).[`execute`](Tool.md#execute)
106
107***
108
109### inputSchema?
110
111```ts
112optional inputSchema: TInput;
113```
114
115Defined in: [packages/ai/src/types.ts:662](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L662)
116
117Schema describing the tool's input parameters.
118
119Can be any Standard JSON Schema compliant schema (Zod, ArkType, Valibot, etc.) or a plain JSON Schema object.
120Defines the structure and types of arguments the tool accepts.
121The model will generate arguments matching this schema.
122Standard JSON Schema compliant schemas are converted to JSON Schema for LLM providers.
123
124#### See
125
126 - https://standardschema.dev/json-schema
127 - https://json-schema.org/
128
129#### Examples
130
131```ts
132// Using Zod v4+ schema (natively supports Standard JSON Schema)
133import { z } from 'zod';
134z.object({
135 location: z.string().describe("City name or coordinates"),
136 unit: z.enum(["celsius", "fahrenheit"]).optional()
137})
138```
139
140```ts
141// Using ArkType (natively supports Standard JSON Schema)
142import { type } from 'arktype';
143type({
144 location: 'string',
145 unit: "'celsius' | 'fahrenheit'"
146})
147```
148
149```ts
150// Using plain JSON Schema
151{
152 type: 'object',
153 properties: {
154 location: { type: 'string', description: 'City name or coordinates' },
155 unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
156 },
157 required: ['location']
158}
159```
160
161#### Inherited from
162
163[`Tool`](Tool.md).[`inputSchema`](Tool.md#inputschema)
164
165***
166
167### lazy?
168
169```ts
170optional lazy: boolean;
171```
172
173Defined in: [packages/ai/src/types.ts:708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L708)
174
175If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools).
176
177#### Inherited from
178
179[`Tool`](Tool.md).[`lazy`](Tool.md#lazy)
180
181***
182
183### metadata?
184
185```ts
186optional metadata: Record<string, any>;
187```
188
189Defined in: [packages/ai/src/types.ts:711](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L711)
190
191Additional metadata for adapters or custom extensions
192
193#### Inherited from
194
195[`Tool`](Tool.md).[`metadata`](Tool.md#metadata)
196
197***
198
199### name
200
201```ts
202name: TName;
203```
204
205Defined in: [packages/ai/src/types.ts:612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L612)
206
207Unique name of the tool (used by the model to call it).
208
209Should be descriptive and follow naming conventions (e.g., snake_case or camelCase).
210Must be unique within the tools array.
211
212#### Example
213
214```ts
215"get_weather", "search_database", "sendEmail"
216```
217
218#### Inherited from
219
220[`Tool`](Tool.md).[`name`](Tool.md#name)
221
222***
223
224### needsApproval?
225
226```ts
227optional needsApproval: boolean;
228```
229
230Defined in: [packages/ai/src/types.ts:705](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L705)
231
232If true, tool execution requires user approval before running. Works with both server and client tools.
233
234#### Inherited from
235
236[`Tool`](Tool.md).[`needsApproval`](Tool.md#needsapproval)
237
238***
239
240### outputSchema?
241
242```ts
243optional outputSchema: TOutput;
244```
245
246Defined in: [packages/ai/src/types.ts:683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L683)
247
248Optional schema for validating tool output.
249
250Can be any Standard JSON Schema compliant schema or a plain JSON Schema object.
251If provided with a Standard Schema compliant schema, tool results will be validated
252against this schema before being sent back to the model. This catches bugs in tool
253implementations and ensures consistent output formatting.
254
255Note: This is client-side validation only - not sent to LLM providers.
256Note: Plain JSON Schema output validation is not performed at runtime.
257
258#### Example
259
260```ts
261// Using Zod
262z.object({
263 temperature: z.number(),
264 conditions: z.string(),
265 forecast: z.array(z.string()).optional()
266})
267```
268
269#### Inherited from
270
271[`Tool`](Tool.md).[`outputSchema`](Tool.md#outputschema)