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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context: light_weight_mode drops dimensional_breakdowns and is charged identically, form_type defaults to 10-K and varies by jurisdiction, and the equivalence to POST /api/v1/data/facts. This goes beyond the annotations without contradicting them.

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 dense and packed with necessary details, front-loading the core purpose and then layering usage guidance, parameter specifics, and a pointer to documentation. While it is longer than some, every sentence earns its place and there is no fluff. It could be slightly more compact but is well-organized.

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 parameters and no output schema, the description covers identification methods, defaults, edge cases (foreign/Korean forms), the light_weight_mode option, and charging note. It also points to external documentation for tiers/limits. Nothing essential for correct selection and invocation is missing.

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?

Although schema description coverage is 100%, the description adds meaning beyond the schema: fact_ids must be 1–500 items each ≤128 chars and are for line-item names (pointing to query_line_items); light_weight_mode's effect on the payload; form_type defaults and jurisdiction-specific values; and the mutual exclusivity of filing_id vs ticker+fiscal_year. This significantly aids correct invocation.

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 begins with a specific verb and resource: 'Fetch specific XBRL facts for a single filing by fact_id.' It clearly differentiates from query_line_items by stating that line-item-name queries (revenue, net income, etc.) should use that tool instead, which prevents confusion among the large sibling set.

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 names the alternative tool (query_line_items) and the condition for using it. It also details how to identify the filing (filing_id or ticker + fiscal_year + optional quarter), and provides guidance on form_type for foreign issuers and Korean filings. This is comprehensive 'when-to-use' guidance.

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