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

Annotations only give generic flags (readOnlyHint=false, openWorldHint=true), so the description carries the safety and side-effect burden — and it delivers richly: invoke performs a one-off install without bloating the toolkit; credential/paid cases return connect or checkout/top-up links, then "the user opens it, then you retry"; "Writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin". It even documents that publish_prompt returns a shareable link that opens without login. Far exceeds what the annotations convey.

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 ~250-word description is a single dense paragraph with no visual hierarchy — no sentence breaks for stages like FLOW / MODES / PROMPT LIBRARY / PERMISSIONS, no bullets, no front-loaded summary line stripped from the flow. Every sentence carries information (low waste), but for a tool with 14 actions and two feature domains, the wall-of-text format makes rapid parsing difficult. This is not conciseness; it's under-structuring a legitimately large tool.

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 extreme complexity (23 params, 14 actions, no output schema, minimal annotations), the description covers an enormous surface: the full search→describe→invoke flow, the not-installed execution path, credential and payment retry loops, the install-vs-invoke decision, permission requirements, installed_in_toolkit vs installed_in_workspace flags, and the entire prompt-library domain. Gaps remain — 'resume' is never explained, and params like 'immediate', 'conversation', and 'tier_slug' are unaddressed — which costs it the 5, but the completeness for the primary user journey is exceptional.

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 for the critical dispatch parameter: every action enum value except 'resume' is behaviorally defined (search/describe/invoke/install/list_tools/report_bug/request_mcp/search_prompts/get_prompt/publish_prompt/subscribe/cancel). It also ties the key params to their roles (describe uses mcp_id, invoke uses tool_id + arguments). However, with 23 parameters there are gaps: 'limit', 'immediate', 'conversation', 'tier_slug', and 'message' get no explicit explanation, and 'resume' is only implied by the subscribe/cancel grouping. Strong compensation, 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 opening line — "The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them" — precisely names the resource, the action (marketplace operations), and its scope (catalog plus execution). It immediately distinguishes from siblings like authenticate, connect, and the SEFAZ tool by stating it's the discovery + invocation layer, and even carves out a second domain (prompt library) explicitly. The verb/scope contract is 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?

Explicit when-to/which-action guidance throughout: "prefer invoke for a single/occasional use", "Use install only to make an MCP PERMANENT in the active toolkit", "subscribe/cancel handle per-MCP billing", and "request_mcp asks us to build a NEW MCP when nothing fits". The core flow (search → describe → invoke) is spelled out with a concrete condition — "invoke works even when the MCP is NOT installed" — plus retry instructions for credential and payment cases. This is direct, actionable routing for the agent.

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