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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds behavioral value by disclosing that it returns 'how many more companies may fit because the decisive value is not published' – a non-obvious behavior that helps the agent interpret results. It also implies a fuzzy matching approach ('meet engineering requirements') without promising exact matches. 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?

The description is three sentences and front-loads the core purpose with examples, followed by calling instructions and return behavior. It is efficient and avoids repetition of schema details. The only minor inefficiency is that the second sentence lists both parameters and the return value in one line, but it remains clear and scannable.

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 read-only search tool with 15 parameters (1 required) and no output schema, the description adequately covers how to invoke it (category required, others optional), the parameter alignment with match_components, and what the result looks like (companies, matching products, and a count of additional potential matches). It does not mention pagination, result limits, or ordering, but given the annotations and the fact that it's a read-only search, these are minor gaps. It is sufficiently complete for an agent to use it correctly.

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 description coverage is 100%, so all parameters are individually documented. The description adds cross-referencing value by noting that requirement parameters are 'same names and units' as match_components, which aids consistency and reduces ambiguity. It also gives usage examples that illustrate how to combine parameters (e.g., 'Chinese companies making star trackers better than 10 arcsec'). This goes beyond what the schema provides, earning a 4 rather than a baseline 3.

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 states a specific verb ('find'), a resource ('suppliers'), and a clear purpose: companies whose products meet engineering requirements in a category. It gives concrete examples ('who makes platforms for GEO') that distinguish it from sibling tools like match_components (which matches components, not companies) and find_alternatives. The purpose is unambiguous and distinct.

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 explicitly instructs to pass 'category, optional country and any requirement parameter of match_components (same names and units)', telling the agent exactly how to call it. It also explains the return value (companies with matching products and an estimate of additional companies). It does not explicitly state when not to use it or name alternative tools, but the reference to match_components implies its role in the selection flow. Clear context, though a direct comparison to siblings would be stronger.

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