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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds critical domain context: absence from the list does not imply untrustworthiness, and the data includes a confidence rating (A-grade) backed by specific sources. It also explicitly disclaims any commercial rating or endorsement, which prevents misinterpretation. It does not detail return format beyond the schema, but with an output schema present, that is not required. This goes beyond annotations to add meaningful nuance.

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 structured into labeled sections (Purpose, Guidelines, Limits, Ex), which aids scanning. It is dense but every sentence serves a purpose: defining the scope, providing usage direction, clarifying limitations, and showing examples. It is longer than typical but justified by the complexity of the trust concept. Minor deduction for length; it could be trimmed slightly without losing value.

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 simplicity of the parameters (all optional, well-documented in schema) and the presence of an output schema (not shown but implied), the description fully covers what an agent needs to know: what the tool returns, how to filter, how to interpret results (trust layer), and how to integrate with get_company. No critical information is missing; the limitations are clearly stated (max 100 rows, no endorsement). The tool is complete for its purpose.

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 100% description coverage, so the baseline is 3. The description adds value by recommending language='en' and response_format='json' for downstream automation, and by mentioning the limit parameter in the example. This exceeds the schema by providing usage context for parameters, hence a 4.

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 ('return'), a specific resource ('every company/project carrying verified=true'), and the precise filtering criterion (A-grade confidence backed by government filings or official announcements). It is distinct from sibling tools like get_company (which retrieves full detail) and query_companies (which likely performs general search), and it explicitly positions itself as the 'trust layer' for shortlisting. The purpose is unambiguous and well differentiated.

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 explicit guidance: 'call this first for any recommendation, shortlisting or transaction-style task.' It also names the alternative (get_company) and explains when to use it ('for full detail on the chosen entity'). It even gives parameter recommendations (language='en', response_format='json' for automation). This is textbook-level usage guidance, covering when and when-not, which is rare and highly valuable.

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