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

Goes well beyond the annotations (which only provide readOnly, openWorld, idempotency, and destructive flags) by explaining auth/payment requirements (needs credential/login, wallet empty → retry after user resolves), permission levels for writes (requires admin), and the distinction between permanent and one-off execution. Also notes that invoke returns a connect link if auth needed. This is rich 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 long but well-structured, front-loading the core marketplace concept and then detailing the action flow TWICE (once in the flow sentence and once in the list of features). It could be trimmed, but the density of information is high and the logical flow (search→describe→invoke) is clear. Slightly verbose, but justifiable given the tool's 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 absence of an output schema and the large parameter set, the description explains the key behaviors, auth/payment implications, and how it integrates with the toolkit. It covers the prompt library and distinguishes installed vs. workspace states. However, it doesn't detail parameter semantics for all 23 parameters, nor does it specify the exact shape of search results beyond 'full profile' – but that's partially compensated by the action flow. Some minor gaps remain, but overall it's quite 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?

The description explains the key parameters implicitly (action, mcp_id, tool_id) via the flow, but many parameters (mcp_id, tool_id, arguments, immediate, prompt_body, etc.) are not explicitly described. With 23 params and 0% schema description coverage, the description only partially compensates. It doesn't clarify argument formats or how prompt_params work, leaving gaps for the agent.

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 is exceptionally clear: it states the tool is the mcp.ai marketplace and catalog, handles capability requests, and outlines the core flow (search → describe → invoke). It explicitly distinguishes between permanent install and one-off invocation, which is the primary purpose distinction. This goes well beyond a vague 'marketplace' label.

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?

Provides explicit guidance on when to use each action: 'action=search discovers MCPs by keyword', 'describe returns full profile', 'invoke RUNS the tool', and specifically states to use install only for recurring use and invoke for one-off use. It also differentiates from sibling tools by covering the prompt library and list_tools. This is fully actionable for an agent.

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