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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description still adds genuine value by disclosing the ten-concept coverage cap and the 200-value return ceiling, though it says nothing about how the accession is obtained or about pagination for the capped result set.

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?

Three tight sentences with the core action and scope front-loaded, followed by output volume and exclusions. The investment-advice disclaimer is slightly off-topic but does usefully bound agent expectations.

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 list tool with a full output schema, the description covers what is returned, the concept scope, and the volume ceiling, so return-format detail is correctly delegated to the output schema. The remaining gap is the origin of the accession and the unexplained limit argument.

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 0% and there are two parameters. The description clarifies that filing_id is a filing accession (the schema only gives a regex pattern), but the 'limit' parameter is never mentioned or explained—'up to 200 reported values' is a hard ceiling, not guidance on the limit argument or its default of 50.

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?

Names a specific verb and resource ('Read XBRL facts tagged to one filing's accession') and bounds the scope to ten supported concepts, which is far more precise than the bare name. It distinguishes itself from list_filings only indirectly through the 'does not return all company periods' exclusion, so it stops short of a 5.

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?

Usage is implied by the negative statements ('does not return all company periods') which nudges the agent toward a company-wide sibling, but it never names compare_filing, list_filings, or read_filing_section, nor states the condition that selects one. Adequate but the routing is left to inference.

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