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

ServerTool.md

271 lines6.2 KB

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