recommend_components

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

Annotations already indicate readOnly, openWorld, and idempotent hints. The description adds value by elaborating on the return format (pass/fail/unknown evidence and Pareto shortlist), which aligns with the openWorldHint. It does not contradict annotations and provides extra behavioral detail beyond the structured hints.

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 concise, two sentences long, and front-loaded with the core action. Every word contributes to explaining the tool's purpose and output. No unnecessary detail or repetition exists.

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 tool has a complex nested request schema and no output schema, but the description does not explain how to structure the request or interpret results beyond mentioning evidence and Pareto shortlist. While the annotations help clarify safety and open-world behavior, the description alone is insufficient for an agent to fully understand the tool's usage in context, especially given 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 input schema has zero description coverage and the sole 'request' parameter is a complex nested object with many required subfields. The description only hints at 'critical requirements' without naming or explaining any parameters such as project_summary, search_terms, quantity, or hard_requirements. This fails to compensate for the schema's lack of parameter documentation.

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 a specific verb 'Find' and resource 'project candidates', clearly indicating what the tool does. It also specifies the output ('pass/fail/unknown evidence and a Pareto shortlist'), distinguishing it from sibling tools like get_recommended_products which likely focus on product recommendations rather than project-level candidate evaluation.

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 clear context by stating 'after critical requirements are known', implying this tool should be used once requirements are finalized. However, it does not explicitly name alternatives or explain when not to use this tool, so it falls short of the most explicit guidance.

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