Whatever message this page gives is out now! Go check it out!
Tool Discovery Rules
Last update:
May 18, 2026
Before an agent or client can call a tool, it must discover what tools exist and what they do.
Overview
Before an agent or client can call a tool, it must discover what tools exist and what they do. MCP standardizes this through
tools/list and the tool metadata returned by your server. How Tools Are Discovered
Clients typically follow this sequence:
- Initialize the MCP session (e.g., via
initialize) to learn server info and capabilities. - Call
tools/listto retrieve a catalog of tools, each including:name– unique tool identifierdescription– human-targeted explanation of purpose and behaviorinputSchema– JSON Schema for the tool’s arguments- Optional metadata (categories, tags, stability, etc.)
The result is cached client-side and used by agents to plan which tools to call for a given user request.
Rules for Visibility
From a user perspective:
- The tool list should include only tools that are valid to call in the current context.
- Tools that are deprecated, internal, or behind feature flags should either:
- Be excluded from
tools/list, or - Be clearly marked as non-recommended in their description and metadata.
- Be excluded from
Your MCP server may also apply:
- Permission filters – restricting tools based on user identity, tenant, or role.
- Stability filters – excluding tools marked as experimental in production clients.
- Tag filters – exposing only tools matching certain tags (e.g., read, stable) requested by the client.
What Users Can Expect
When you ask an MCP-enabled agent “What can you do?”, the agent will:
- Use
tools/listunder the hood. - Present tool capabilities grouped or summarized by their descriptions.
You should expect:
- The tool list to be stable and predictable across sessions with the same server and permissions.
- New tools to appear only when your team releases them; they won’t “self-invent”.
- Tools to include enough description and schema metadata to be understandable without referring to internal code.
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
