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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description richly discloses behavior: invoke works even when the MCP is not installed and does a one-off run without bloating the tool list; missing credentials trigger a connect link; a paid MCP with empty wallet triggers a checkout/top-up link followed by retry; and writes require workspace owner/admin. It also flags installed_in_toolkit vs installed_in_workspace and that publish_prompt links work without login. This is genuinely valuable behavioral context.

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 dense and fairly long, but nearly every sentence carries distinct information: the install-vs-invoke distinction, one-off run behavior, credential/checkout links, owner/admin requirements, and the prompt library. The long run-on sentences could be better structured, but the front-loaded opening is effective and there is little redundant repetition.

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 (23 parameters, 0 required, no output schema), the description covers the important behavioral edge cases: one-off invoke, connect and checkout links, write permissions, and prompt-library flows. The main completeness gap is that parameters are not mapped systematically to operations, and the sibling tool boundaries (report_bug/connect/authenticate) are left ambiguous — but the description is still far above average for such a multi-action 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?

Schema description coverage is 0% across 23 parameters, so the description must compensate. It does explain the central `action` enum meanings (search, describe, install, invoke, subscribe/cancel, prompt ops) and mentions the tool_id/cost/auth workflow. But most parameters (cancel_reason, conversation, prompt_package, report_context, arguments, tier_slug, prompt_vars, etc.) are never mapped to any semantic workflow, leaving a large burden unresolved.

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 identifies this as the mcp.ai marketplace — 'the in-platform catalog of every MCP/tool, AND the way to run them' — and lays out the core search → describe → invoke flow. It distinguishes this from MCPs themselves and from sibling tools, but it is a mega-tool covering 10+ sub-operations (report_bug, subscribe, prompt library, install, etc.), so the singular purpose is broad.

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 gives valuable decision guidance: 'prefer invoke for a single/occasional use' vs 'use install only to make an MCP PERMANENT', plus how list_tools, subscribe/cancel, report_bug, and request_mcp fit. However, it doesn't address overlaps with siblings (e.g., an actual sibling report_bug tool exists, and connect/authenticate siblings are relevant when invoke returns a connect link).

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