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

ServerTool.md

277 lines6.4 KB

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
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
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']
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)