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

Annotations only provide basic flags (readOnlyHint=false, openWorldHint=true, etc.), but the description adds substantial behavioral context: invoke works even when the MCP is not installed without bloating the tool list, writes require workspace owner/admin, and specific responses include connect links or checkout/top-up links. This goes far beyond the annotations and no contradiction is present.

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 long (300+ words) but dense and well-organized, front-loading the core purpose and flow before diving into details. Every sentence carries useful information, and the structure (catalog flow, invoke vs install, permissions, prompt library) is logical. It could be trimmed slightly, but overall it earns its length for a tool of this complexity.

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 (multi-action dispatcher, 23 parameters, no output schema), the description is remarkably complete. It explains the search→describe→invoke flow, one-off execution semantics, permission requirements, billing/auth related responses, and the prompt library subfeatures. It also mentions return behaviors (full profile, prompt text, shareable links), covering the conceptual response landscape without an output schema.

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 schema_description_coverage at 0% and 23 parameters, the description must compensate. It does explain the core action parameter and the roles of mcp_id, tool_id, and arguments through the flow narrative. However, many parameters (e.g., immediate, tier_slug, cancel_reason, prompt_vars, prompt_targets) are not individually described, leaving gaps in semantic understanding for those less obvious fields.

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 the tool as the official mcp.ai marketplace and execution platform, with a specific verb+resource framing: 'the in-platform catalog of every MCP/tool, AND the way to run them.' It distinguishes itself from siblings by enumerating its unique actions (search, describe, invoke, install, prompt library) and explaining the core flow.

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 when-to-use guidance, especially for invoke vs install: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit.' It also explains the decision flow (search → describe → pick tool_id → invoke) and conditions for connect/checkout links, giving clear context for choosing this tool over alternatives.

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