Skip to main content
Tools are the interface between a service and its consumers. Each tool is a typed function with input/output schemas and metadata about its behavior.

​
ToolDefinition

interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: Record<string, any>;
  outputSchema: Record<string, any>;
  streaming?: boolean;
  mutation: boolean;
}
FieldRequiredDescription
nameYesTool identifier (becomes part of the namespaced tool name: serviceName_toolName)
descriptionYesWhat the tool does — used by AI agents to decide when to use it
inputSchemaYesJSON Schema for the tool’s input parameters
outputSchemaYesJSON Schema for the tool’s return value
streamingNoWhether the tool returns a stream instead of a single response (default false)
mutationYesWhether 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

Set streaming: 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

ValueBehavior
falseRead-only operation — safe to call speculatively
trueWrite operation — the AI agent may ask for confirmation before calling