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

Annotations (openWorldHint=true, readOnlyHint=false) match the description; no contradiction. The description adds significant context beyond annotations: invoke's one-off execution without toolkit bloat, the connect-link and checkout/top-up-link behaviors for auth/payment, and the owner/admin requirement for writes. It also discloses that search/describe flag installation status. Slightly docked because it omits details like pagination/limits on search and exact return shapes, but the permission and side-effect disclosures are strong.

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?

Every sentence earns its place — there's no fluff — but the description is a single dense ~230-word paragraph enumerating 14 actions. The crucial invoke-vs-install guidance ('KEY: invoke works even when the MCP is NOT installed') is buried mid-paragraph rather than lead or bulleted. For a tool this polymorphic, separating the MCP actions, the prompt-library actions, and the auth/billing notes into scannable segments would greatly improve usability.

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 complex 23-parameter, multi-action gateway with no output schema, the description is remarkably thorough: it covers the search→describe→invoke pipeline, install vs invoke semantics, permission requirements, billing/auth behaviors, prompt-library flow, and even the mcp.ai/p/<slug> sharing behavior. Gaps: it never describes what search/describe/search_prompts actually return (no result-shape expectations) and the timeout/retry semantics for the described 'then you retry' flow are vague. Still, given zero schema descriptions, the coverage punches well above its weight.

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 the description must compensate — and it does for the core parameters: action (all 14 enums explained in prose), mcp_id, tool_id, arguments ('pick the right tool_id → invoke RUNS that tool'), and prompt_slug/prompt_vars (via the publish/get_prompt explanations). However, among 23 total parameters, several receive no semantics anywhere: cancel_reason, cancel_comment (enum has 8 values), tier_slug, immediate, request_name, request_details, report_context, conversation, prompt_category, prompt_targets, and prompt_description. A substantial tail of undocumented parameters remains.

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 establishes this as the mcp.ai marketplace gateway ('the in-platform catalog of every MCP/tool, AND the way to run them'), positioning it distinctly from workspace-level siblings like authenticate/connect. However, 'purpose' is inherently fragmented across 14 distinct action values (search, describe, invoke, install, publish_prompt, etc.), making the tool a kitchen-sink dispatcher rather than a single-verb resource. The core verb is ambiguous without the action parameter.

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?

Outstanding guidance: explicitly walks the core flow ('search discovers MCPs by intent → describe returns one MCP's full profile... → invoke RUNS that tool'), gives a clear decision rule between invoke vs install ('Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use'), and specifies when to use each auxiliary action (list_tools/report_bug/request_mcp/subscribe/cancel). It even explains the prompt-library vs MCP-tool distinction ('MCPs and the PROMPT LIBRARY... is about ready-made prompt TEXT rather than MCPs').

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