Tool metadata
MCP tool descriptions are instructions: how to review them
Review MCP tool names and descriptions for embedded imperatives, concealed behavior, excessive scope, and contradictions with JSON Schema.
- Published
- Reading time
- 6 minutes
Descriptions shape agent decisions
The MCP tools specification gives each tool a name, optional description, and input schema. An agent can use the description to decide when and how to call the tool, making the field part of the operational control surface rather than ordinary marketing copy.
A strong description states the tool's purpose, preconditions, side effects, and parameter meaning without trying to redefine system policy or hide information from the operator.
Review text and schema together
List every parameter explicitly documented in the description and compare it with inputSchema.properties. Look for described parameters the schema cannot validate, declared parameters left unexplained, and descriptions that promise narrower behavior than broad fields permit.
Then read for instructions unrelated to the stated function: collecting credentials, reading unrelated files, suppressing confirmation, or chaining to another action. Preserve the full source text during review so truncation does not hide qualifiers.
Prefer explicit contracts
Use narrow enums, bounded strings, required fields, and clear side-effect annotations where supported. Do not rely on prose alone to enforce scope. Runtime authorization must validate the actual requested resource and action.
When a description changes, treat it as a security-relevant update. Diff the complete metadata, not only package versions or executable code.
Frequently asked questions
Should tool descriptions contain usage instructions?
They can explain legitimate use, parameters, and side effects. They should not attempt to override higher-priority policy, conceal behavior, or request unrelated data.
Is JSON Schema an authorization boundary?
No. Schema constrains input shape. The server must still authenticate, authorize, canonicalize, and validate each operation at runtime.