get_mcp_tool_catalog

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of behavioral disclosure. It discloses the key behavioral trait: research tools are excluded unless explicitly opted in. However, it doesn't describe the return format, pagination, or what 'explicit opt-in' means operationally (e.g., whether include_research=true is the opt-in mechanism). The description adds some value but leaves the opt-in mechanism to be inferred from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with zero waste. The core action ('Return the public tool catalog') is front-loaded, and the critical behavioral caveat ('research tools require explicit opt-in') is appended in the same breath. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple catalog-listing tool with 3 optional parameters and no output schema, the description is mostly adequate. The main gap is that it doesn't explain what 'category' and 'stability' filter on, and it doesn't clarify the return shape. Given the tool's low complexity, this is a minor-to-moderate gap, so a 3 is appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It partially does by explaining the 'include_research' concept ('research tools require explicit opt-in'), which maps to the include_research parameter. However, it doesn't explain the 'category' or 'stability' parameters at all, and with 0% schema coverage, the agent must guess at their semantics. The description adds some meaning but doesn't fully compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Return') and resource ('public tool catalog'), and adds a scoping qualifier ('public') that distinguishes it from research-oriented catalog tools. It doesn't explicitly name a sibling alternative, but the qualifier plus the 'research tools require explicit opt-in' clause gives enough differentiation from the many sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool: when you need the public catalog, and it warns that research tools are not included unless explicitly opted in. It doesn't name a specific alternative tool, but the opt-in warning effectively tells the agent not to expect research tools here and to look elsewhere or pass include_research=true. This is clear context without explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.