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

Annotations are minimal (readOnlyHint=false, no idempotent/destructive hints), so the description carries the full burden and delivers richly. It discloses that invoke runs a tool one-off without installing it ('without adding the MCP to the toolkit and without bloating the tool list'), that credential/payment gaps return connect/checkout links requiring user action then retry, that install is permanent, and that write operations need workspace owner/admin. This significantly extends behavioral knowledge beyond the structured fields. 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?

This is a dense ~450-word single paragraph with no bullets, line breaks, or sectioning, making it hard to scan. It front-loads the core purpose and flow well, but the invoke explanation is redundant ('runs it pontualmente (one-off)' repeated with 'without adding... without bloating'), and the PROMPT LIBRARY section is appended as a trailing clause. Every sentence carries some information, but the wall-of-text format undermines usability for an agent parsing on the fly.

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 (23 params, 14 actions, no output schema, sparse annotations), the description covers the workflow thoroughly: the search→describe→invoke pipeline, install vs invoke tradeoffs, billing/auth links, and the prompt-library sub-flow. However, it omits parameter semantics (limit, tier_slug, prompt_targets, cancel_reason, etc.) and never explains the return value shape — with no output schema, the agent cannot know what invoke or describe returns on success beyond the connect/checkout link mentions. Adequate for workflow, incomplete on data contract.

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 fully, but it does not. It thoroughly explains the action enum (all 14 values are described in prose) and implies mcp_id/tool_id/arguments through the flow narrative, but the remaining ~17 parameters (limit, message, immediate, tier_slug, conversation, cancel_reason, cancel_comment, prompt_body, prompt_slug, prompt_tool, prompt_title, request_name, prompt_targets, report_context, request_details, prompt_description, prompt_category) are completely unexplained in both schema and description. The action field is well-served, but the bulk of parameters are opaque.

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 establishes this as 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' with a defined core flow (search → describe → invoke). It names specific capability intents ('find an MCP that does X', 'consulta um CPF') which makes the purpose concrete. However, the tool spans 14 actions plus a prompt library, so the purpose is somewhat diffuse rather than a single verb+resource; the description handles this well overall but doesn't crisply state 'this tool performs one job'.

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 is provided: the core flow is spelled out step-by-step ('action=search discovers MCPs by intent → describe returns one MCP's full profile... → invoke RUNS that tool'). It gives a clear decision rule for invoke vs install ('Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use'), states auth requirements ('Writes... require workspace owner/admin'), and covers the retry flow when credentials or payment are needed. It also tells when to use list_tools, subscribe/cancel, report_bug, and request_mcp, including the fallback 'request_mcp asks us to build a NEW MCP when nothing fits.'

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