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

Annotations only provide readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds significant behavioral context: invoke runs one-off without installing, returns connect/checkout links when needed, writes require workspace owner/admin, and search/describe flag installation status. It does not contradict annotations. It could mention that invoke may have side effects (e.g., running a tool) but the description already covers the one-off nature and auth/payment flows.

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 that is information-rich but not well structured. It front-loads the core flow but then covers many sub-features in a run-on manner. It could benefit from bullet points or clearer separation of the marketplace vs prompt library sections. However, every sentence adds value, so it's not verbose, just poorly formatted.

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 the tool's complexity (14 actions, 23 params, no output schema), the description is quite complete. It covers the main flows, auth requirements, payment handling, and the prompt library. It doesn't explain return values (no output schema), but that's acceptable. It could mention the 'resume' action and the 'immediate' parameter, which are not explained, but overall it's sufficient for an agent to use the tool effectively.

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. It explains the key parameters implicitly: action (with all enum values explained), mcp_id, tool_id, arguments, prompt_* fields for the prompt library, and tier_slug for billing. It does not explicitly map every parameter (e.g., limit, query, immediate, conversation, report_context, request_details), but the action-based flow covers most usage. Given 23 parameters and 0% coverage, the description does a good job of explaining the main ones but leaves some gaps.

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 the tool is the official mcp.ai marketplace catalog and execution platform, covering both discovery and running of MCPs. It distinguishes itself from siblings by explicitly naming the core flow (search → describe → invoke) and the prompt library sub-features, which differentiates it from tools like authenticate, connect, or tribunal_tjsp_segundo_grau_consultar.

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 guidance on when to use invoke vs install ('prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT'), and covers when to use search, describe, list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt library functions. It also explains the flow for handling connect links and checkout links, which is actionable guidance.

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