ToolDefinition
interface ToolDefinition {
name: string;
description: string;
inputSchema: Record<string, any>;
outputSchema: Record<string, any>;
streaming?: boolean;
mutation: boolean;
}
| Field | Required | Description |
|---|---|---|
name | Yes | Tool identifier (becomes part of the namespaced tool name: serviceName_toolName) |
description | Yes | What the tool does — used by AI agents to decide when to use it |
inputSchema | Yes | JSON Schema for the tool’s input parameters |
outputSchema | Yes | JSON Schema for the tool’s return value |
streaming | No | Whether the tool returns a stream instead of a single response (default false) |
mutation | Yes | Whether the tool changes state (write operation) vs. read-only |
Example
export const TOOLS = {
listRepositories: {
name: "listRepositories",
description: "List repositories for the authenticated user",
inputSchema: {
type: "object",
properties: {
per_page: { type: "number", description: "Results per page (max 100)" },
sort: {
type: "string",
enum: ["created", "updated", "pushed", "full_name"],
description: "Sort field",
},
},
},
outputSchema: {
type: "array",
items: {
type: "object",
properties: {
id: { type: "number" },
full_name: { type: "string" },
language: { type: "string" },
},
},
},
streaming: false,
mutation: false,
},
createRepository: {
name: "createRepository",
description: "Create a new repository",
inputSchema: {
type: "object",
properties: {
name: { type: "string", description: "Repository name" },
private: { type: "boolean", description: "Whether the repo is private" },
},
required: ["name"],
},
outputSchema: {
type: "object",
properties: {
id: { type: "number" },
full_name: { type: "string" },
html_url: { type: "string" },
},
},
streaming: false,
mutation: true,
},
} as const;
Streaming tools
Setstreaming: true for tools that return data incrementally. Streaming handlers return an AsyncGenerator:
streamMessage: async function* (args: any, context: AuthenticatedServiceContext<Settings, CustomAuth>) {
const client = createClient(context);
const stream = await client.messages.create({ ...args, stream: true });
for await (const event of stream) {
if (event.type === "content_block_delta") {
yield event.delta.text;
}
}
},
Mutation flag
| Value | Behavior |
|---|---|
false | Read-only operation — safe to call speculatively |
true | Write operation — the AI agent may ask for confirmation before calling |