Interface ToolDefinition

Extension metadata advertised on this tool's tools/list descriptor.

Use vendor-namespaced keys for custom data. This definition metadata is distinct from a tool callback result's _meta: it describes the tool, while result _meta belongs to one invocation. For view-bound or visibility-restricted tools, framework-owned MCP Apps keys are derived from ToolDefinition.view and ToolDefinition.visibility; those derived values take precedence over colliding entries here.

Behavioral hints for clients (readOnlyHint, destructiveHint, …).

LLM-facing description of what the tool does.

Tool icons advertised on tools/list, in author order. Absolute HTTP(S) and data URLs pass through; paths relative to public/ become absolute asset URLs for HTTP requests. Entrypoint hosts prefer these icons over server branding. Use monochrome SVGs with currentColor for ChatGPT.

Object schema for input validation — any Standard Schema library with JSON Schema conversion (StandardSchemaWithJSON): zod v4, ArkType, Valibot, …. Field descriptions become LLM hints. Input is validated by the SDK before the callback runs. Emitted on the wire as inputSchema.

Unique tool identifier, e.g. "fetch-weather".

Schema for structured output (StandardSchemaWithJSON). Any JSON root is allowed — object, array, or primitive (2026-07-28 protocol). When set, the callback must return a result carrying matching structuredContent or an explicit isError result — enforced at compile time and validated by the SDK at runtime.

Alias for ToolDefinition.inputSchema. Prefer inputSchema in new code — it matches the MCP wire field name.

How the tool may be called on an OAuth server. Checked before the callback runs, and advertised on tools/list for hosts such as ChatGPT.

• [{ type: "noauth" }]: anyone may call it; ctx.auth is set when the caller is signed in.
• [{ type: "noauth" }, { type: "oauth2", scopes }]: anyone may call it. The scopes are only advertised, so the callback checks ctx.auth?.scopes itself.
• [{ type: "oauth2", scopes }]: sign-in required with every listed scope plus the provider's requiredScopes.

Omitted means sign-in with the provider's requiredScopes. noauth requires mixedAuth: true on the server.

Human-readable title shown in UIs (falls back to name).

Bind this tool to a view for MCP Apps rendering. Requires ToolDefinition.outputSchema — the view reads the result's structuredContent typed by this schema.

Declares who may call or see the tool. Emitted as _meta.ui.visibility on tools/list. Omitted = host default (callable by the model, visible to the app). The server always lists every registered tool — hosts filter by this declaration; the server never omits tools from tools/list. "app" marks app-private helper tools callable from views via useCallTool while the host hides them from the model.