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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description adds valuable behavioral context: invoke runs tools even when not installed, returns connect/checkout links when credentials/payment are needed, and 'Writes require workspace owner/admin.' It also clarifies the distinction between permanent install and one-off invoke, and the prompt library's separate purpose. Minor gaps remain (e.g., no explicit disclosure of uninstall side effects), but overall it is highly transparent.

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 dense block of text (~200 words) but every sentence contributes meaningful information about core flow, edge cases, permissions, or the prompt library. It is front-loaded with the purpose and clearly organized, although bullet points or short sections would enhance scannability. It is appropriately sized for a tool with 14 actions.

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 this complexity and no output schema, the description covers the major workflows, permissions, and special link behaviors. However, it omits return values for several actions (search, describe, list_tools), does not explain parameters like immediate or conversation, and leaves out error handling and edge-case behaviors (e.g., resume). It is useful but not fully complete.

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 23 parameters and 0% schema description coverage, the description must compensate heavily. It explains the meaning of the action values and the key tool_id parameter, but many parameters (limit, immediate, tier_slug, conversation, prompt_vars, cancel_comment, etc.) are not semantically described. The description focuses on behavior and flow, leaving parameter mechanics largely to the schema, which has no descriptions.

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 '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 also explicitly covers capability requests and describes the core search→describe→invoke flow, distinguishing it from sibling tools like authenticate and 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?

The description provides explicit usage guidance: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT.' It also explains when to use list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt library functions, offering clear alternatives and reasoning.

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