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

Beyond the readOnlyHint annotation, the description discloses crucial behaviors: it never invents numbers, may return SAFE_REFUSAL as an honest response, and performs FX conversion with provenance. This adds meaningful context that annotations alone do not convey.

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 compact and front-loaded. The first sentence states purpose, the second explains refusal semantics, and the third covers currency conversion. Every sentence provides necessary information without fluff.

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 tool's complexity (4 params, output schema present), the description covers key aspects: certified values, refusal handling, and currency conversion. It does not mention ambiguous query handling, but the output schema and schema-rich parameters fill most gaps.

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 100%, so baseline is 3. The description adds value by explaining how target_currency and usd_only relate to post-recall conversion, and clarifies the default reporting currency, which enhances parameter understanding.

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 opens with 'Certified SEC fact query' – a specific verb and resource. It clearly differentiates the tool by emphasizing provenance and non-invention, distinguishing it from sibling tools like query_sec_metric_exact or query_sec_sector_peers.

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?

Provides concrete usage guidance: how to handle SAFE_REFUSAL, how to request FX conversion via target_currency/usd_only or natural language, and the default currency behavior. However, it does not explicitly state when to prefer this tool over its siblings.

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