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

With annotations that are all near-default values (readOnly=false, destructive=false), the description carries the full transparency burden and delivers: it discloses that writes require workspace owner/admin, that invoke runs tools 'pontualmente' without permanent installation, and that credential/payment gaps return connect or checkout links requiring user action before retry. No contradiction exists — the write-permission statements are consistent with readOnlyHint=false.

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 unbroken paragraph — a dense wall of text with no section breaks or bullet points. While nearly every sentence carries some information, the lack of structure makes the middle sections (billing, install vs invoke, prompt library) blur together and burdens the agent's parsing. It front-loads purpose well but is neither concise nor well-organized.

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 this complex (23 params, 14 actions, billing, installs, prompt library) with no output schema and minimal annotations, the description covers the core discovery and run flows thoroughly, including auth requirements and retry behavior. But it leaves gaps: no return-value descriptions, no cancel/resume flow details, and unexplained immediate/tier_slug semantics. It is adequate for the main paths but not complete for a tool of this magnitude.

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 0% schema coverage and 23 parameters, the description faces a heavy burden and compensates only partially. It explains the action enum values, the tool_id selection flow, arguments for invoke, prompt_vars variable filling, and prompt_slug sharing links. However, many parameters remain entirely unexplained — cancel_reason, cancel_comment, immediate, tier_slug, conversation, request_name, request_details, prompt_body, prompt_targets, report_context — leaving real gaps.

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 sentence identifies this as 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them', which is a specific and accurate purpose. It clearly explains the search→describe→invoke core flow and differentiates this catalog tool from siblings like connect and authenticate. However, the scope is sprawling (14 actions spanning billing, installs, and a prompt library), making the tool's verb diffuse despite the strong opening.

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 internal usage direction: the explicit core flow (search→describe→invoke), the clear 'prefer invoke for one-off, use install only for permanent' heuristic, and the retry-after-connect/checkout-link logic. It also positions list_tools for what is callable right now and distinguishes the prompt library actions. It lacks explicit when-not-to-use versus sibling tools, but the internal action guidance is genuinely helpful.

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