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

Annotations provide readOnlyHint=false and openWorldHint=true, but the description adds crucial behavior beyond that: invoke works even when the MCP is not installed, runs one-off without adding to the toolkit, returns connect links for credential needs, and returns checkout/top-up links for payment. It also states that writes require workspace owner/admin and that prompt library links open without login. This is substantial context not captured by annotations.

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, long block but every sentence contributes useful information about the many actions and behaviors. It is front-loaded with the overall purpose, though it could be better structured with bullets or separate sections for the MCP catalog flow vs the prompt library. It is not overly verbose, but its length is at the edge of acceptable.

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 14 actions and no output schema, the description covers most behavioral outcomes: describe returns a full profile, invoke returns connect/checkout links, publish_prompt returns a shareable link, and list_tools enumerates callable tools. Minor gaps remain (e.g., 'resume' is only listed without explanation, 'immediate' param is not described), but overall it is sufficiently complete for the complexity.

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%, so the description must compensate. It explains the core parameters (action, mcp_id, tool_id, arguments) and some prompt-related params, but leaves many others undocumented (e.g., immediate, limit, prompt_targets, prompt_category, request_details). The description does not systematically map all 23 parameters, leaving gaps that the schema also does not fill.

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 — the in-platform catalog of every MCP/tool, AND the way to run them.' It goes on to enumerate the core actions (search, describe, invoke, install, etc.) and the prompt library, making the tool's multi-purpose nature explicit and distinct from siblings like authenticate or toolkit_info.

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 guidance on when to use each action and how they relate: 'Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile ... → invoke RUNS that tool.' It also gives clear when-not guidance: 'Use install only to make an MCP PERMANENT in the active toolkit; prefer invoke for a single/occasional use.' This strongly differentiates the alternatives.

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