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

The description goes far beyond annotations, explaining nuanced runtime behaviors: invoke is one-off and does not bloat the tool list, credential gaps produce connect links, wallet gaps produce checkout links and instruct to retry, install makes tools appear natively in future sessions, and search/describe surfaces installed_in_toolkit vs installed_in_workspace. It also notes that writes (install/uninstall/subscribe/cancel plus the one-off install behind invoke) require owner/admin. No contradictions with 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 long but dense and highly organized: a summary sentence, core flow, key behavioral notes, action-by-action guidance, auth constraint, and prompt library subsection. Every sentence adds operational value; there is no padding or redundancy. For a tool with 14 actions and 23 parameters, the length is proportionate and the flow is logical.

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?

The description is remarkably complete for a complex tool with no output schema. It covers all 14 actions, the request flow, fallback behaviors (connect/checkout links and retry), permission requirements, differentiation between invoke and install, and the separate prompt library. It even gives example capability queries ('find an MCP that does X', 'consulta um CPF'). An agent could select and invoke the correct action confidently based on this alone.

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 and 23 parameters, the description carries the full burden and succeeds. It explains the key action values and connects them to parameters: describe returns full profile with id+params+pricing+auth so you pick the right tool_id, invoke runs that tool, search discovers MCPs by intent, prompt actions handle prompt_text with {{variables}}. Even fields like prompt_slug and prompt_vars are contextualized via the shareable-link description. This adds meaning far beyond the bare 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 opens with a crisp definition: 'THE official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It clearly identifies the resource (marketplace) and verbs (search, describe, invoke, install, etc.), and distinguishes it from sibling tools like authenticate/connect by positioning it as the catalog/execution layer. The action list is explicitly enumerated, leaving no ambiguity about scope.

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 a full decision framework: core flow (search→describe→invoke), explicit when-to-use-invoke-vs-install ('invoke works even when the MCP is NOT installed' and 'prefer invoke for a single/occasional use' vs 'install only to make an MCP PERMANENT'), plus coverage of every sibling action (list_tools, subscribe/cancel, report_bug, request_mcp, prompt actions). It also states auth requirements for writes (requires workspace owner/admin), giving agents clear go/no-go conditions.

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