/**
 * 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 SIX 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, all four set
 * explicitly (directories reject a tool that leaves one implicit, and
 * the spec defaults are the pessimistic ones). A hint describes the
 * tool as a whole, so a tool with any write action is not read-only
 * and a tool with any overwrite / remove / archive action is
 * destructive. Per-action risk (billable / irreversible) is spelled
 * out in the description so the model warns the user first.
 *
 * 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";
/** MCP tool hints. Required here, unlike in the protocol, so a new tool
 *  cannot ship with a hint left to the spec's pessimistic default. */
export interface ToolAnnotations {
    /** No action changes anything. */
    readOnlyHint: boolean;
    /** Some action overwrites, removes or archives (not only additive). */
    destructiveHint: boolean;
    /** Repeating a call with the same args has no further effect. */
    idempotentHint: boolean;
    /** Reaches outside the TracePass account (the open web, third parties). */
    openWorldHint: boolean;
}
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: ToolAnnotations;
    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