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

Annotations indicate readOnlyHint=false, but the description goes far beyond annotations: it explains that invoke runs tools even when the MCP is not installed, that it doesn't bloat the toolkit, and that writes require workspace owner/admin. It also details the difference between one-off invoke and permanent install, and the implications for future sessions. This transparency clearly exceeds what annotations provide.

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 quite long but packed with essential information. It is well-structured with a logical flow from discovery to execution, and covers the prompt library separately. While every sentence adds value, the length is borderline; however, given the tool's complexity (23 parameters, 14 actions, multiple subsystems), the length is justified. It could be slightly more concise but is not wasteful.

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 high complexity (23 parameters, 14 actions, no output schema, no parameter descriptions), this description is remarkably complete. It explains the entire workflow, the distinction between one-off invoke and permanent install, auth/payment handling, the prompt library subsystem, workspace permissions, and the installed_in_toolkit vs installed_in_workspace flags. There is no output schema to explain, and the description covers all major behavioral aspects. This is as complete as one could expect for such a multi-faceted 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?

With 0% schema description coverage, the description fully compensates by explaining the semantic roles of key parameters: action controls the action type, mcp_id identifies the MCP, tool_id selects the tool, message contains the prompt, arguments carries invocation args, and prompt_* fields belong to the prompt library. It also explains the meaning of action values and the interplay between parameters (e.g., search needs query, describe needs mcp_id, invoke needs tool_id and arguments). This compensates for the lack of parameter descriptions in the schema.

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 states that this is 'the official mcp.ai marketplace' for discovering and running MCPs. It specifies the core workflow (action=search discovers MCPs, describe returns profiles, invoke runs tools), and distinguishes itself from sibling tools like authenticate and toolkit_info. The purpose is explicit and covers the catalog and execution capabilities.

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 extensive usage guidance: when to use search, describe, invoke, install, and list_tools, with explicit recommendations like 'prefer invoke for a single/occasional use' and 'use install only to make an MCP PERMANENT.' It also explains the behavior for auth and payment scenarios ('invoke returns a connect link' if credentials needed, 'checkout/top-up link' if wallet empty). This is exemplary guidance for choosing among the actions.

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