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

Annotations are minimal (readOnlyHint=false, idempotentHint=false, etc.), so the description carries the burden of behavioral disclosure. It clearly explains key behaviors that are not inferable from annotations: 'invoke works even when the MCP is NOT installed', link-returning behavior for credentials/payment, permission requirements ('Writes ... require workspace owner/admin'), and the behavior of returned links ('opens without login'). It also describes what the search/describe flags indicate, adding substantial behavioral depth.

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 a single dense paragraph of ~230 words that effectively front-loads the core purpose and then details the action flow. Every sentence adds new information, from credential/payment link behavior to permission requirements to the prompt library. However, the lack of bullet points or section breaks reduces scannability given the amount of content.

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, no output schema, and 14 actions, the description covers an impressive amount: the core flow, install/invoke distinction, auth/billing edge cases, permissions, and the prompt library subspace. It misses some actionable details (e.g., expected values for `conversation`, `immediate`, or how to use `tier_slug`) and does not describe error handling or return formats, but it is far more complete than the average description for such a complex 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 schema coverage at 0%, the description must compensate, and it does well for the most critical parameter (`action`), explaining the semantics of each enum value through flows, and references `tool_id` and the data returned by `describe`. However, several parameters like `conversation`, `immediate`, `tier_slug`, `report_context`, and `request_details` remain undocumented, and the description does not explicitly cover all 23 parameters. Still, it provides strong contextual meaning for the primary workflow, far exceeding typical compensation.

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 specific identification: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' which clearly defines the tool's role. It further enumerates its scope in concrete domains (capability requests, CPF lookup, tool search) and differentiates between internal actions (search/describe/invoke/install) with explicit roles. This clearly separates it from siblings like sefaz_pe_crf_movel_consultar or show_version.

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?

It provides explicit when-to-use guidance, e.g., 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT.' It also names alternatives ('list_tools lists what is callable right now', 'request_mcp asks us to build a NEW MCP when nothing fits'). The 'Core flow' maps actions to stages, giving clear decision criteria.

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