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

Annotations are thin (readOnlyHint:false, openWorldHint:true, destructiveHint:false), so the description bears the transparency burden and delivers richly: one-off invoke 'runs the tool pontualmente... without bloating the tool list,' auth-needing MCPs 'return a connect link,' paid-with-empty-wallet returns 'a checkout/top-up link,' and 'Writes... require workspace owner/admin.' No contradiction with annotations—the write-capability implied by readOnlyHint:false is consistent with install/uninstall/invoke.

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?

Every sentence carries distinct informational weight—core flow, one-off invoke, install persistence, subordinate actions, permission requirements, and the prompt library. However, ~300 words are packed into a single unbroken paragraph; breaking out the prompt-library section or the action catalog would aid scannability. Dense but not bloated.

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 tool with 14 actions, 23 parameters, no output schema, and minimal annotations, this description is remarkably complete: it covers the search→describe→invoke pipeline, offline invoke behavior, auth and billing fallback flows, install-vs-invoke tradeoffs, permission tiers, and the whole prompt-library subsystem including output hints ('returns a shareable mcp.ai/p/<slug> link'). Minor gaps (the 'resume' action and 'immediate' param go undescribed) but these are trivial against the full surface area handled.

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, and it does substantially: it maps action→parameter usage (query for search, mcp_id for describe, tool_id+arguments for invoke, prompt_slug/prompt_vars for get_prompt). However, it leaves roughly half the 23 parameters unexplained (immediate, tier_slug, conversation, cancel_reason, request_details, prompt_targets). Strong compensation but not exhaustive given 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 opening line defines the tool precisely: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It then states the core search→describe→invoke flow with specific verbs, and distinguishes the tool's sub-actions from its siblings (authenticate, connect, toolkit_info). For a 14-action tool, the purpose statement is unambiguous and grounded.

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?

Provides explicit when-to-use guidance with named alternatives: 'prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT'; 'subscribe/cancel handle per-MCP billing; report_bug sends feedback; request_mcp asks us to build a NEW MCP when nothing fits.' It even warns when invoke returns a connect/checkout link and instructs 'the user opens it, then you retry.' No score could reflect this better.

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