tool

function

Declare a capability the AI agent can call during a turn. This is the one member of the trio the user does not trigger. The model reads `description` and decides on its own whether to call, so write that field for the model, not for a menu. Say what the tool does and when it is the right choice. `command` and `slashCommand` are the user-triggered neighbours. The input contract is derived from the annotation on `run`'s first parameter, so there is no schema to hand-write and no second place for the shape to drift. The handler runs in the ext-host with full Node access. Its context carries the calling session, the tool call id, an activity channel for progress, and a cancellation signal worth honoring on long work. Tools go under `ai.tools` in `defineMod`, not in `commands`.

function tool<TName extends string, TInput>(toolValue: PlainToolInput<TName, TInput>): PlainTool<TName, TInput> function tool<TName extends string, TInput, TResult>(toolValue: RenderedToolInput<TName, TInput, TResult>): RenderedTool<TName, TInput, TResult>

Import

import { tool } from '@modular/sdk';

Notes

example: ```ts tool({ name: 'review_search', description: 'Search the workspace for a term and return matching lines.', run: async (input: { readonly query: string }, ctx) => { await ctx.tool.activity.update({ kind: 'status', text: 'searching' }); const hits = await search(input.query, ctx.cancellationSignal); return hits.join('\n'); }, }); ```
category: Authoring