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

Annotations only say readOnlyHint=false, destructiveHint=false, and openWorldHint=true — no detail on auth, side effects, or errors. The description carries full burden and delivers: one-off invoke semantics without toolkit pollution, connect-link and checkout-link flows with retry instruction, workspace owner/admin requirement for writes, and the distinction between installed_in_toolkit vs installed_in_workspace. This goes far beyond what annotations declare and adds genuine decision-relevant behavior. No contradiction with annotations; both imply a stateful, write-capable tool.

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 wall of text well over 200 words with no paragraph breaks, bullets, or scannable structure — a scope of 14 distinct actions deserves at least some visual organization. Credit for a strong front-loaded opening sentence that captures the essence, and for the useful parenthetical clarifications like 'the user opens it, then you retry'. But the density harms scannability for an agent that must quickly extract timing/condition rules.

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?

This is a maximally complex surface — 23 params, a 14-value action enum, no output schema — and the description covers the dominant flows end-to-end: search → describe → invoke, the install-vs-invoke decision, auth/wallet error paths, permission requirements, and the prompt library sub-API. It falls just short of 5 because coverage is uneven: the prompt library and cancellation flows get comparatively thin treatment, and the error/retry model beyond the connect/checkout cases is unstated. Still remarkable completeness relative to tool complexity.

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% with 23 parameters and 0 required, pushing the full burden onto the description. The description names the action=enums (search, describe, install, invoke, etc.) and loosely implies behaviors for them, but no parameter is given meaningful semantics. Critically, it never explains that `arguments` takes a JSON string, what `conversation` is for, what `tier_slug` selects, what `message` contains, or how `immediate` and `resume` behave — an agent could not safely construct an invoke() call from this alone. Baseline 3 or higher is impossible with zero compensation for 23 undocumented params.

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 opening line 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them' clearly identifies the verb+resource with a specific scope. Some points deducted because 'marketplace' as a name embraces 15+ distinct actions (search, describe, invoke, install, publish, etc.), and the description never steps back to state a single crisp purpose — it does distinguish the tool from siblings only by virtue of covering everything, not through pointed differentiation.

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 when-to-use guidance: 'prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT', and 'prefer invoke' when credentials/wallet are needed with the connect/checkout link flow. It also names concrete alternatives within the tool ('list_tools lists what is callable right now', 'request_mcp asks us to build a NEW MCP when nothing fits'). This exceeds the bar for explicit if/when/alternative guidance.

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