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

No annotation contradiction found; the description actually expands on the annotations' implications. The readOnlyHint: false is honored and enriched with detail that invoke triggers one-off installs, returns connect/checkout links for auth/payment, and that writes require owner/admin. The description discloses permissions, the point-in-time behavior of invoke, the link-return-and-retry pattern, and that installed_in_toolkit vs installed_in_workspace flags differ — all useful behavioral context an agent can't infer from the schema alone.

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 information-dense and every sentence does add value, but it's a single unbroken paragraph that mixes catalog discovery, invocation semantics, auth/billing nuances, prompt-library functionality, and permission restrictions. The 'KEY:' aside is a useful emphasis technique, but the lack of scannable structure (bullets, sentence cases) means an agent must grimly parse the whole statement to find the relevant behavior. It's compact, but it's compaction over structure.

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 high-complexity, multi-action tool with 23 parameters and no output schema, the description covers the flagship flows well — including the non-obvious 'invoke returns a connect link then you retry' pattern and the permission model. But completeness for this tool is measured across its breadth (actions covered: search/describe/install/invoke/list_tools/subscribe/cancel/report_bug/request_mcp and all four prompt-library flows), and in that breadth, some flows are papered over: report_bug, resume, and request_mcp get name-checks only, with no parameters or response behavior described. Decent breadth, but the actions are of very different granularity and the descriptions don't scale to the tool's scope.

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 coverage is 0% and the description is the ONLY source of parameter meaning, yet it references only action, query, mcp_id, and tool_id conceptually — leaving 19 of 23 parameters (including structured types like arguments, prompt_targets, cancel_reason, conversation) completely undocumented. The description also never maps which fields pair with which action values (e.g., which params describe expects). With zero schema description and zero parameter guidance, agents must guess at the field composition rules, which is a significant gap for a 23-parameter tool.

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 states this is the official mcp.ai marketplace for discovering and running MCPs, with a stated core flow (search → describe → invoke). However, the tool bundles 14 different actions and two distinct subsystems (billing + prompt library), which fragments the 'resource' being described. It's specific and goes well beyond the tautological name, though it could more crisply state 'lists/installs/manages MCPs and prompts' as a single-sentence purpose.

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 provides strong usage guidance for when to use invoke vs install ('prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT'), and it excludes billing/feedback/request actions. However, the guidance is buried in a dense monologue rather than structured, and since this is a single tool dispatching on an 'action' enum, the 'vs alternatives' comparison is largely internal to the description itself. Some alternatives (subscribe vs cancel) are implied in the billing flow but not explicitly compared.

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