Interface ToolDefinition<TInput>

Tool definition - the canonical type for MCP tools.

This is the ONLY type needed for defining and registering tools. Used by defineTool(), ToolRegistry, and McpServerBuilder.

Example

const greetTool = defineTool({
  name: 'greet',
  description: 'Greet a user by name',
  input: z.object({ name: z.string() }),
  handler: async ({ name }, ctx) => text(`Hello, ${name}!`),
});

interface ToolDefinition<TInput extends ZodTypeAny = ZodTypeAny> {
    _meta?: Record<string, unknown>;
    annotations?: ToolAnnotations;
    description: string;
    handler: (
        args: TypeOf<TInput>,
        context: ToolContext,
    ) => Promise<
        {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            content: (
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    text: string;
                    type: "text";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "image";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    data: string;
                    mimeType: string;
                    type: "audio";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    description?: string;
                    icons?: {
                        mimeType?: string;
                        sizes?: (...)[];
                        src: string;
                        theme?: "light" | "dark";
                    }[];
                    mimeType?: string;
                    name: string;
                    title?: string;
                    type: "resource_link";
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    resource: | {
                        _meta?: { [key: string]: unknown };
                        mimeType?: string;
                        text: string;
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        blob: string;
                        mimeType?: string;
                        uri: string;
                    };
                    type: "resource";
                }
            )[];
            isError?: boolean;
            structuredContent?: { [key: string]: unknown };
            [key: string]: unknown;
        },
    >;
    input: TInput;
    name: string;
    requiredScopes?: readonly string[];
}

Type Parameters

TInput extends ZodTypeAny = ZodTypeAny
Zod schema type for input validation (default: any Zod type)

Index

Properties

_meta? annotations? description handler input name requiredScopes?

Properties

`Optional` `Readonly`_meta

_meta?: Record<string, unknown>

Optional metadata passed through to the MCP SDK tool registration.

This is a generic passthrough for protocol-level metadata like { ui: { resourceUri: 'app://my-app' } } used by MCP Apps. The framework does not interpret _meta — it is forwarded as-is.

`Optional` `Readonly`annotations

annotations?: ToolAnnotations

Optional annotations providing hints about tool behavior.

Per MCP specification, annotations help clients understand tool characteristics without needing to parse the description. These are hints, not guarantees.

See

https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations

`Readonly`description

description: string

Human-readable description shown to LLM

handler

handler: (
    args: TypeOf<TInput>,
    context: ToolContext,
) => Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        content: (
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                text: string;
                type: "text";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "image";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "audio";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                description?: string;
                icons?: {
                    mimeType?: string;
                    sizes?: (...)[];
                    src: string;
                    theme?: "light" | "dark";
                }[];
                mimeType?: string;
                name: string;
                title?: string;
                type: "resource_link";
                uri: string;
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: ((...) | (...))[];
                    lastModified?: string;
                    priority?: number;
                };
                resource: | {
                    _meta?: { [key: string]: unknown };
                    mimeType?: string;
                    text: string;
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    blob: string;
                    mimeType?: string;
                    uri: string;
                };
                type: "resource";
            }
        )[];
        isError?: boolean;
        structuredContent?: { [key: string]: unknown };
        [key: string]: unknown;
    },
>

Tool handler function.

Type Declaration

- (
      args: TypeOf<TInput>,
      context: ToolContext,
  ): Promise<
      {
          _meta?: {
              "io.modelcontextprotocol/related-task"?: { taskId: string };
              progressToken?: string | number;
              [key: string]: unknown;
          };
          content: (
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  text: string;
                  type: "text";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  data: string;
                  mimeType: string;
                  type: "image";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  data: string;
                  mimeType: string;
                  type: "audio";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  description?: string;
                  icons?: {
                      mimeType?: string;
                      sizes?: (...)[];
                      src: string;
                      theme?: "light" | "dark";
                  }[];
                  mimeType?: string;
                  name: string;
                  title?: string;
                  type: "resource_link";
                  uri: string;
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  resource: | {
                      _meta?: { [key: string]: unknown };
                      mimeType?: string;
                      text: string;
                      uri: string;
                  }
                  | {
                      _meta?: { [key: string]: unknown };
                      blob: string;
                      mimeType?: string;
                      uri: string;
                  };
                  type: "resource";
              }
          )[];
          isError?: boolean;
          structuredContent?: { [key: string]: unknown };
          [key: string]: unknown;
      },
  >
- Parameters
  - args: TypeOf<TInput>
    Validated input (typed from Zod schema)
  - context: ToolContext
    Execution context with progress reporter, abort signal
  Returns Promise<
      {
          _meta?: {
              "io.modelcontextprotocol/related-task"?: { taskId: string };
              progressToken?: string | number;
              [key: string]: unknown;
          };
          content: (
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  text: string;
                  type: "text";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  data: string;
                  mimeType: string;
                  type: "image";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  data: string;
                  mimeType: string;
                  type: "audio";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  description?: string;
                  icons?: {
                      mimeType?: string;
                      sizes?: (...)[];
                      src: string;
                      theme?: "light" | "dark";
                  }[];
                  mimeType?: string;
                  name: string;
                  title?: string;
                  type: "resource_link";
                  uri: string;
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: ((...) | (...))[];
                      lastModified?: string;
                      priority?: number;
                  };
                  resource: | {
                      _meta?: { [key: string]: unknown };
                      mimeType?: string;
                      text: string;
                      uri: string;
                  }
                  | {
                      _meta?: { [key: string]: unknown };
                      blob: string;
                      mimeType?: string;
                      uri: string;
                  };
                  type: "resource";
              }
          )[];
          isError?: boolean;
          structuredContent?: { [key: string]: unknown };
          [key: string]: unknown;
      },
  >
  MCP CallToolResult (use response helpers: text(), json(), error())

`Readonly`input

input: TInput

Zod schema for input validation

`Readonly`name

name: string

Unique tool name (e.g., 'greet', 'list_servers')

`Optional` `Readonly`requiredScopes

requiredScopes?: readonly string[]

Scopes required to execute this tool (RBAC).

When set, the framework checks authInfo.scopes BEFORE the handler executes. All listed scopes must be present (AND logic). If the check fails, a 403 Forbidden error is returned.

Omit or set to undefined for tools accessible to any authenticated user.

Interface ToolDefinition<TInput>

Example

Type Parameters

Index

Properties

Properties

`Optional` `Readonly`_meta

`Optional` `Readonly`annotations

See

`Readonly`description

handler

Type Declaration

Parameters

`Readonly`input

`Readonly`name

`Optional` `Readonly`requiredScopes

Settings

On This Page

Interface ToolDefinition<TInput>

Example

Type Parameters

Index

Properties

Properties

Optional Readonly_meta

Optional Readonlyannotations

See

Readonlydescription

handler

Type Declaration

Parameters

Readonlyinput

Readonlyname

Optional ReadonlyrequiredScopes

Settings

On This Page

`Optional` `Readonly`_meta

`Optional` `Readonly`annotations

`Readonly`description

`Readonly`input

`Readonly`name

`Optional` `Readonly`requiredScopes