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

The description goes well beyond the minimal annotations (readOnlyHint: false, openWorldHint: true). It discloses that invoke works even when the MCP is not installed, runs one-off, and doesn't bloat the tool list. It explains auth/payment behavior: 'invoke returns a connect link' for credentials and 'checkout/top-up link' if the wallet is empty, then says to retry. It also states that writes require workspace owner/admin. No contradictions 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 well-structured with a clear progression: marketplace definition, core flow, key invoke behavior, permission note, and prompt library. However, it is quite long and dense, with some verbose phrases like 'pontualmente' and the included example 'consulta um CPF'. While most sentences earn their place, it could be trimmed slightly for brevity.

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 complex tool with 14 actions and no output schema, the description is remarkably thorough. It explains the main workflows, edge cases (login required, wallet empty), and permissions. It even covers the separate prompt library. However, a few parameters and action-specific return structures remain vague, so it is not a perfect 5 but is close.

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 23 parameters and 0% schema description coverage, the description must compensate. It explains key parameters like 'action', 'tool_id', 'arguments', and the 'prompt_' group, but many parameters (e.g., 'limit', 'immediate', 'tier_slug', 'conversation', 'message') are not explicitly described. The high-level action flow implies meanings for some, but gaps remain, so it only partially compensates for the missing schema descriptions.

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 clearly identifies this as the mcp.ai marketplace for discovering, running, and managing MCPs and prompts. It lists specific actions with verbs like 'search', 'describe', 'invoke', and 'install', and distinguishes itself from siblings by explaining the marketplace's unique role: 'catalog of every MCP/tool, AND the way to run them.' The core flow is explicitly spelled out, making the tool's purpose 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?

Provides explicit when-to-use guidance: 'Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile ... → invoke RUNS that tool.' It differentiates between 'invoke' for one-off uses ('prefer invoke for a single/occasional use') and 'install' for permanent additions ('Use install only to make an MCP PERMANENT in the active toolkit'). Also states that 'list_tools lists what is callable right now' and explains permission requirements. This is far beyond a generic description.

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