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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behaviors: invoke runs a tool one-off without adding it to the toolkit, returns a connect link if a credential is needed, returns a checkout/top-up link if the wallet is empty, and writes require workspace owner/admin. This is far richer than the annotations alone and sets clear expectations for side effects and retry logic.

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 single dense paragraph, but nearly every sentence adds distinct information: core flow, invoke vs. install trade-offs, auth/billing behavior, permissions, and the prompt library. It is long but justified by the tool's complexity. Minor deduction for at least one rambling sentence (the one starting 'KEY: invoke works even...') that could be split for readability.

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 (23 params, no output schema, sparse annotations), the description is remarkably complete. It explains the end-to-end workflow, edge cases (credentials, empty wallet), permission model, and even the prompt library sub-interface. An agent would have enough context to select the right action and parameters for most scenarios, including how to handle connect/checkout links and retries.

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 23 parameters and 0% schema description coverage, the description must compensate. It adds semantic meaning to the most important parameters via the core flow (e.g., action, tool_id, arguments) and names the prompt-related actions (search_prompts, get_prompt, publish_prompt). However, many parameters like prompt_body, cancel_reason, and request_details are not individually explained, so the description only partially covers the parameter space.

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 opens with 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' clearly defining the tool's function and scope. It distinguishes this from sibling tools (e.g., openfinance_*) by focusing on the marketplace and MCP execution rather than a specific domain.

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 an explicit core flow ('action=search ... → describe ... → invoke RUNS that tool'), explains when to prefer invoke over install ('prefer invoke for a single/occasional use'), and notes additional use cases like 'search_prompts finds one, get_prompt returns its full text'. It also mentions permission requirements for writes, giving clear when-to and when-not-to guidance.

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