/**
 * MCP tool definitions for the TracePass v1 API.
 *
 * The v1 surface has ~23 endpoints. Exposing 23 flat MCP tools would
 * swamp the model's tool list and slow tool selection. Instead the
 * surface is grouped into FIVE resource tools, each taking:
 *   - `action` — a required enum naming the operation;
 *   - `args`   — an object whose required shape DEPENDS on `action`.
 *
 * MCP's `inputSchema` is one Zod shape per tool and can't natively
 * branch on `action`. So `args` is declared permissively, and each
 * handler validates `args` against the SPECIFIC per-action Zod
 * schema — the per-action rigor is kept, it just lives in the
 * handler. A model that omits a required arg gets a precise error
 * (`ACTION_SCHEMAS` powers both the validation and the messages).
 *
 * Every tool's `description` documents each action and its `args`.
 * `annotations` carry MCP hint flags at the tool level; per-action
 * risk (billable / irreversible) is spelled out in the description
 * so the model warns the user before a destructive action.
 *
 * Transport-agnostic: `buildTools(client)` binds the handlers to a
 * `TracePassClient`; the server factory registers them.
 */
import { z } from "zod";
import type { TracePassClient } from "./api-client.js";
import { type ToolResult } from "./result.js";
export interface McpToolDefinition {
    name: string;
    title: string;
    description: string;
    inputSchema: z.ZodRawShape;
    /** Declared shape of the tool's structured result, so MCP clients (and
     *  catalogues like Smithery) can validate + display the output. The tools
     *  pass v1 API JSON straight through, so this describes that envelope. */
    outputSchema: z.ZodRawShape;
    annotations: {
        readOnlyHint?: boolean;
        destructiveHint?: boolean;
        idempotentHint?: boolean;
    };
    handler: (args: Record<string, unknown>) => Promise<ToolResult>;
}
/**
 * Build the 5 grouped tools, bound to a TracePass API client.
 */
export declare function buildTools(client: TracePassClient): McpToolDefinition[];
//# sourceMappingURL=tools.d.ts.map