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

Despite annotations already carrying readOnly=false, openWorld=true, idempotent=false, destructive=false, the description adds substantial behavioral detail: invoke runs one-off without installing or bloating the tool list, credential gaps return a connect link, payment gaps return a checkout/top-up link, writes require workspace owner/admin, and the prompt share link opens without login. These behaviors are not visible in the annotations and are clearly disclosed.

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 long but densely informative and thematically organized: core flow first, then invoke-specific caveats, billing/auth, write-permission context, and the separate prompt library. Every sentence adds value, but the sheer volume of detail makes it harder to parse quickly; better paragraph breaks would help.

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 14-action dispatcher with no output schema and 23 undocumented parameters, the description is unusually complete: it covers discovery, invocation, one-off vs permanent install, auth, payment, permissions, billing actions, and prompt-library behavior. Still, some actions are omitted (resume is never described, uninstall only appears in the permissions sentence) and it does not describe expected return shapes, which would be materially useful for a no-output-schema tool.

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 carries a heavy burden, and it does decode the action enum and core flow concepts like action, query, mcp_id, tool_id, and arguments. However, many parameters are left completely untouched: limit, immediate, tier_slug, request_name, cancel_reason, cancel_comment, report_context, prompt_body, prompt_slug, prompt_tool, prompt_vars, conversation, prompt_title, prompt_description, prompt_targets, prompt_category, and request_details. The agent must infer much of the parameter semantics from names and defaults alone.

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 states an exact purpose: it is the mcp.ai marketplace used to discover, describe, and run MCPs/tools. It explains the core action flow (search -> describe -> invoke) and explicitly names the intent categories it covers ('find an MCP that does X', 'consulta um CPF'). It also separates the prompt-library function from the MCP-catalog function, making the dual nature clear and avoiding confusion with sibling tools.

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 gives explicit when-to-use guidance: prefer invoke for single/occasional use, use install only to make an MCP PERMANENT, use list_tools to see callable tools now, subscribe/cancel for per-MCP billing, report_bug for feedback, and request_mcp when nothing fits. It even tells the agent what to do when a connect or checkout link is returned (user opens it, then retry). This is strong routing guidance.

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