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

Annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds meaningful behavioral context: invoke runs tools without installing them or bloating the toolkit, install persists MCPs into the active toolkit, missing credentials yield a connect link, insufficient wallet balance yields a checkout link, and writes require workspace owner/admin. This substantially adds context beyond annotated flags, although it doesn't discuss rate limits or exact failure result shapes.

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 and information-dense, but every sentence earns its place by covering a distinct sub-area: discovery flow, invoke one-off semantics, credential/payment edge cases, install persistence, billing/support paths, workspace permissions, and prompt library. The structure is stream-of-consciousness rather than bullets or numbered flow, so it could be more scannable, but content is not redundant or padded.

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?

Given that the tool has an enormous 23-parameter schema with 0% coverage and no output schema, the description does an exceptional job of making the tool usable: it explains the search→describe→invoke core flow, the one-off vs permanent distinction, auth via connect links and payment via checkout links, admin ownership requirements, and prompt library flows. There are always more edge cases that could be enumerated, but this description is substantially complete for a variant-rich marketplace tool with no structured parameter documentation.

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% (the schema has 23 parameters but no per-parameter descriptions), so the description carries the full burden. The text names many parameters (action, limit, query, mcp_id, tool_id, arguments, prompt_* fields, cancel_reason, etc.) and relates them to sub-flows, but it does not explicitly map every named parameter to its type/default/meaning. It covers high-level semantics for important parameters (action=search/describe/install, mcp_id, tool_id, prompt_title/prompt_body/prompt_slug) and improves on an empty schema, earning a 3.

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 states this is the official mcp.ai marketplace—the in-platform catalog of every MCP/tool AND the way to run them. It enumerates concrete capability queries (find an MCP that does X, consulta um CPF, is there a tool for Y) and explicitly distinguishes the tool's sub-actions (search/describe/invoke/install/list_tools/subscribe/cancel/report_bug/request_mcp) from sibling tools like authenticate and show_version. The verb-plus-resource structure makes the tool's purpose unmistakable.

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 provides explicit when-to-use guidance: use `invoke` for one-off/occasional runs even when MCP is not installed, use `install` only to make an MCP permanent, use `search` to discover by intent, `describe` to get a full profile, and `list_tools` to see what is callable right now. It also states credential/payment edge cases (invoke returns connect/checkout links) and warns that writes require workspace owner/admin, which effectively excludes non-admin usage.

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