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

Annotations already flag this as read-only/non-destructive/open-world. The description adds process detail: capability detection, marketplace search, and a recommendation-plus-alternatives response with reasoning. No contradiction 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?

Two sentences plus an example, with the key instruction front-loaded and no filler. The example earns its place by demonstrating the expected input format.

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 annotations, output schema, and the fact that most parameters are optional and self-descriptive, the description covers the essential workflow and expected output. It lacks only explicit pointers to sibling tools or behavior when no MCP matches, which are non-critical for invoking the 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?

The description adds meaning to the required task parameter by framing it as a natural-language goal statement and providing a concrete example. However, with schema coverage at 33%, the five optional preference parameters (pricing, security, deployment, open source) receive no explanation, so the description only partially compensates.

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 uses specific verbs ('detects', 'searches', 'returns') tied to a clear resource (MCPs in the marketplace) and includes a concrete Gmail/Linear example. It clearly separates this capability-discovery tool from siblings like search_resources or compare_mcps.

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?

It tells the agent exactly how to use it – describe the desired AI behavior in natural language – and what happens next. It does not explicitly name sibling tools for exclusion, but the natural-language capability-matching context is clear enough to avoid confusion with direct resource search or comparison tools.

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