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

With only four sparse boolean annotations, the description carries the full burden and delivers: it discloses that invoke runs tools one-off even when NOT installed (key side-effect), that auth and payment follow an interactive link-and-retry pattern, that writes require workspace owner/admin, and that published prompts share via a no-login slug URL. This goes well beyond anything inferable from readOnlyHint=false or openWorldHint=true.

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 text is long (~280 words) but earned its length by covering 14 actions and 23 parameters. It is well-front-loaded (purpose → core flow → key nuances → lesser features), and the 'KEY:' marker usefully flags the most critical behavioral nuance. Minor deductions for density that demands careful reading and the stray Portuguese word 'pontualmente' in an otherwise English description.

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 (14 distinct actions spanning marketplace search, installation, billing, bug reports, and a prompt library), the description covers the high-frequency decision tree exceptionally well but leaves the long tail under-specified: the semantics of `resume`, the cancel/billing flow details, and any output or error contract are absent. Considering the absence of an output schema and required parameters, the description wisely focuses on the 80% case but cannot be called fully complete.

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 earns credit for explaining the semantics of the core data-bearing parameters (action, query, mcp_id, tool_id, arguments, prompt_slug, prompt_vars) through the narrated flow. However, several action-to-parameter mappings remain opaque: `immediate`, `resume`, `conversation`, `message`, `cancel_reason`/`cancel_comment`, and the report_bug/request_mcp parameter sets are never connected to their actions.

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 is a model of clarity: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It names a specific resource (the mcp.ai marketplace), a covering verb/scope (catalog AND execution), and immediately distinguishes itself from siblings like authenticate, connect, and report_bug by establishing itself as the main entry point for discovery and invocation. The core flow (search → describe → invoke) is clearly articulated in one dense sentence.

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 decision criteria for every significant branch: when to choose install vs invoke ('prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT'), when to use list_tools ('lists what is callable right now'), when to use search_prompts vs search, and how to handle credential/wallet-edge cases (return connect/checkout link, user opens, then retry). This is the gold standard for guiding an agent's decision-making.

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