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

With no annotations, the description carries full behavioral disclosure. It transparently explains the discover:true side effect (searches the web, audits new products into the registry, slower and costlier), the filtering behavior, and the return of ranked products with reasons. It does not mention rate limits or auth, but for a tool of this nature these aren't critical.

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, front-loaded with the core purpose. Every sentence adds value: the main behavior, the optional filters, and the discover side effect with cost implications. No fluff, though it could be split into bullets for readability—still appropriately sized.

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?

For a tool with 7 params, no output schema, and a non-trivial discover behavior, the description provides enough to call it correctly: the task input, filter semantics, and the discover trade-off. It doesn't detail the exact output structure, but the description's statement about ranked products with reasons suffices for agent invocation.

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?

Schema coverage is 0%, so the description must explain parameters. It does: 'task' is the natural-language task, optional boolean flags (api/mcp/self_serve/openapi/cli) filter candidates, and 'discover' triggers web search and audit. All 7 params are effectively covered, despite the schema providing no descriptions itself.

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 the tool's function: it takes a natural-language task and returns products (ranked by fit and AgentReady score) that expose required capabilities, each with a reason. This is specific and distinguishes it from siblings like 'search_tools' or 'find_tools_for_task' by highlighting the resolution and ranking behavior.

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 sets clear context—it's for natural-language tasks—and explains optional filtering by capability type and the discover flag for broader web search. It doesn't explicitly name alternatives or state when not to use it, but the context is sufficient for an agent to infer applicability.

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