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

Annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description goes well beyond by explaining key behaviors: invoke runs tools pontualmente without installation, returns connect/checkout links on auth/payment failures, and requires owner/admin for writes (install/uninstall/subscribe/cancel). It also explains prompt library behavior (get_prompt fills {{variables}}, publish returns shareable link). No contradiction with annotations; in fact it clarifies the non-read-only nature. However, it doesn't detail error handling for all actions or what happens on retry.

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 block, front-loaded with the core flow (search→describe→invoke) but then diverges into many details without clear structure. Every sentence adds value, but the long list of actions and prompt library could be organized with bullet points or sections. It is longer than necessary, but not bloated—still, structure could be improved.

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 high complexity (23 params, 14 actions, no output schema), the description is quite thorough. It explains the main flow, the key nuance of invoke (runs without install, returns links), the difference between one-off and permanent install, and the prompt library. It omits specifics on some actions (resume, report_bug detail) but overall provides a functional mental model for the agent. The absence of output schema makes this description crucial, and it does a good job.

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 coverage is 0%, so description must compensate. The description explains the flow but doesn't map specific parameters to actions beyond mentioning action values and key params like mcp_id, tool_id, arguments, prompt_vars. Most parameters (e.g., cancel_reason, prompt_targets, limit) are undocumented in the description, leaving the agent to infer from the schema. This is a gap, but the description's core flow (search/describe/invoke) covers the most critical parameters, earning a baseline 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 that this tool is the central marketplace and dispatcher for MCPs and prompts, covering multiple actions. It distinguishes itself from siblings by listing its sub-actions (search, describe, invoke, etc.) and explicitly mentions the prompt library, which siblings like authenticate or connect don't cover. However, the purpose is broad and could be confused with a general assistant, but it is specific enough as a hub for MCP discovery and execution.

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 clear when-to-use guidance for core actions: use search to find MCPs, describe to get details, invoke for one-off runs, install for permanent ones. It explicitly contrasts invoke vs install ('prefer invoke for a single/occasional use') and mentions that invoke works even without installation. However, it doesn't cover all 14 actions (e.g., resume, report_bug, request_mcp are only implied) and doesn't explicitly say when NOT to use this tool (e.g., when a specific sibling like authenticate would be better).

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