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

The description adds substantial behavioral context beyond the annotations. It explains the one-off execution model of invoke, the connect-link behavior for missing credentials, the checkout/top-up link for insufficient wallet funds, the retry workflow, and the workspace-owner/admin requirement for writes. It also discloses installed_in_toolkit vs installed_in_workspace flagging. This goes far beyond what readOnlyHint/openWorldHint/idempotentHint/destructiveHint convey.

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 every sentence conveys necessary operational or selection information. It is well-structured: core flow, key invoke behavior, install-vs-invoke distinction, other actions, permissions, and the prompt library are separated logically. No filler or repetition exists.

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 with 23 parameters and no output schema, the description covers a remarkable amount: core flows, auth, payment, permissions, installed-status flags, and prompt-library semantics. The only notable omissions are detailed return-value expectations and the resume action, which is listed in the schema but never mentioned in the description. Still, this is highly complete for its complexity.

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, the description carries the burden of explaining parameters. It does explain the meaning of many action values (search, describe, invoke, install, list_tools, etc.) and the role of tool_id in selecting a tool. However, it does not cover numerous non-action parameters such as arguments, immediate, tier_slug, conversation, prompt_vars, cancel_reason, or request_details. It provides high-level action semantics but lacks precise parameter-level guidance, leaving gaps for an agent trying to construct a complete request.

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 clear, specific declaration: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It then names the concrete capability requests it handles ('find an MCP that does X', 'consulta um CPF') and outlines the search → describe → invoke flow. This strongly distinguishes it from siblings like authenticate or connect.

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?

Usage guidance is explicit and comprehensive. It contrasts invoke vs install with direct instruction: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit.' It also clarifies when to use list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt-library functions, providing both positive and negative selection criteria.

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