lean-mcp-tools

Lean MCP tools

A response is paid for when a tool is called. A definition is paid for on every request, called or not, because the client sends all of them with each one. Server instructions sit between: once per session. Put each fact where its audience reads it.

Fact	Goes in
True of every tool ("all durations are in milliseconds")	instructions
Why a caller picks this tool over its neighbour	that tool's description
A value	the response

What a definition holds

• name, title — the display field. annotations.title is a second copy; drop it.
• description — the selection prompt: what it returns, when to pick it, nothing the schema below already says.
• inputSchema — a describe only for what the property name and its type cannot say.
• annotations — only spec hints that differ from the default and carry meaning. destructiveHint and idempotentHint are defined as meaningful only when readOnlyHint is false, so a read-only tool declares readOnlyHint: true and openWorldHint: false and stops. There is no priority hint.

Restructure before you delete

Deleting a fact costs the answer and saves less than reshaping it.

• Ten per-category properties, each inlining the same enum, became z.partialRecord(z.enum(CATEGORIES), z.enum(LEVELS)) — each enum emitted once. ~844 tokens to ~428, wire form unchanged, unknown keys now rejected. (Plain z.record is cheaper still, but marks every key required.)
• Hold the values as an as const tuple and build the schema from it, so no description restates them.

Measure the whole wire object

estimateTokens(JSON.stringify(tool)); // per tool, from a live tools/list over stdio

A budget over {name, description, inputSchema} guards a subset of the cost: it let title, annotations and the SDK's own fields grow ~215 tokens unwatched.

A definition is not finished until a check covers it. Three assertions, in the gate that already runs the server: