ToolDefinition

A single tool definition. The input Zod schema is compiled to JSON Schema for tools/list and used to validate arguments before handler runs.

Type Parameters

Type Parameter	Default type	Description
I extends z.ZodType	z.ZodType	The Zod schema type for the tool’s arguments.
O extends z.ZodType	z.ZodType	The Zod schema type for the tool’s structured output, if declared.

Properties

Property	Type	Description
alwaysOn?	boolean	Budget hint: surface this tool even when the per-session cap is reached.
annotations?	ToolAnnotations	Behavioral hints surfaced in tools/list. Any field the author omits is filled by a conservative default: readOnlyHint is true UNLESS the tool declares write intent (mutating: true, or the server is invoked with a trove:ingest scope). An explicit author value always wins.
description	string	The description Claude reads to decide whether to call this tool.
input	I	A Zod schema describing the tool’s arguments.
mutating?	boolean	Marks the tool as mutating, which forces client consent. Defaults to false.
name	string	A short snake_case identifier, unique within the server.
output?	O	An optional Zod schema describing the tool’s structured output. When set, it is compiled to an outputSchema in tools/list and the handler’s structured field is surfaced as the spec structuredContent object.
title?	string	A human-readable display name for client tool pickers (MCP title).

Methods

handler()

handler(args: output<I>, ctx: ToolContext): Promise<string | ToolResult<NoInfer<output<O>>>>;

The tool’s implementation.

NoInfer on the return side is load-bearing: without it O would also be inferred FROM the returned structured, so the schema and the value would agree by construction and check nothing. Pinning O to the declared output alone is what makes the comparison real.

Parameters

Parameter	Type
args	output<I>
ctx	ToolContext

Returns

Promise<string | ToolResult<NoInfer<output<O>>>>