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

The description discloses far beyond the minimal annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). It reveals the one-off execution semantics of invoke, the connect-link behavior for credential needs, checkout/top-up links for empty wallets, permission requirements (writes require workspace owner/admin), and installed_in_toolkit vs installed_in_workspace flags. This is the model of behavioral transparency — no contradiction with annotations.

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 dense (~250 words) and every sentence earns its place — no fluff or tautology. It front-loads purpose, then flows through the core discover→execute chain, key behaviors, permission notes, and the prompt library. The main weakness is structural: it's a single run-on paragraph where the marketplace core and prompt library could benefit from separation, and the KEY emphasis is capitalized mid-paragraph. Appropriate length given a 14-action, 23-param 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?

For a tool of this complexity (14 actions, 23 params, no output schema, minimal annotations), the description is remarkably complete: it covers the end-to-end flow, auth/financial fallbacks, permission scoping, the installed-vs-invoke distinction, and the entire prompt-library subsystem. With no output schema present, it compensates by describing return behaviors (connect link, checkout link). Minor gaps: not every action's return shape is described, and a few params lack semantic anchoring, but for this scope it is near-comprehensive.

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 description coverage and 23 parameters, the description carries the full burden — and it compensates well by walking through the action flows: action=search/describe/invoke/install, tool_id ('so you pick the right tool_id'), mcp_id, arguments, tier_slug, and the prompt library params (prompt_body, prompt_slug, prompt_description). However, some parameters remain unaddressed (limit, message, immediate, conversation, cancel_reason, cancel_comment, report_context, request_name, request_details, prompt_targets, prompt_vars), so it's not exhaustive despite strong coverage of the key decision-driving 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 description opens with a specific, unambiguous statement: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It then enumerates the core flow (search → describe → invoke) and the prompt-library subsystem, making the tool's dual role (catalog + executor) unmistakable. This clearly distinguishes it from siblings like tribunal_trt2_processo_consultar or report_bug.

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?

Exceptionally explicit guidance: 'KEY: invoke works even when the MCP is NOT installed... prefer invoke for a single/occasional use' contrasted with 'Use install only to make an MCP PERMANENT in the active toolkit.' It also gives when-to-use for every action — list_tools ('lists what is callable right now'), request_mcp ('asks us to build a NEW MCP when nothing fits') — and disambiguates alternatives within the same family.

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