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

Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are enriched by the description's disclosures: invoke runs tools one-off without installation, returns connect/checkout links for credentials/payment, and writes require workspace owner/admin. There is no contradiction with annotations, and the description adds crucial execution and permission context.

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?

The description is a single dense paragraph but front-loads the core purpose and uses signposts like 'Core flow:', 'KEY:', 'Use install only...', and 'Writes...' to organize many actions. Every sentence adds value, though the length could be reduced by splitting into sections or listing actions more compactly.

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?

Given the tool's complexity (14 actions, 23 params) and the absence of output schema and parameter descriptions, the description covers essential workflows, auth/payment edge cases, permission requirements, and the prompt library. It still leaves a few schema elements unexplained (e.g., resume, immediate, tier_slug), making it thorough but not exhaustive.

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?

With 23 parameters and 0% schema description coverage, the description compensates by explaining key parameters (action, mcp_id, tool_id, arguments, prompt_slug, prompt_vars) through workflow narrative. However, several parameters like immediate, tier_slug, resume, cancel_reason, conversation, and prompt_targets are left to inference from names/enums, so the compensation is good but not complete.

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 clearly identifies the tool as the official mcp.ai marketplace and catalog of every MCP/tool, with a specific verb-driven core flow: search, describe, invoke. It provides concrete examples of capability requests and distinguishes itself from sibling tools that are specific MCPs, making its purpose unambiguous.

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 gives explicit decision criteria: 'prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT', and explains when list_tools, report_bug, request_mcp, and prompt actions are appropriate. It also details edge cases (auth and payment links, retry instructions) that guide the agent on next steps.

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