fundamentals

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

No annotations are provided, so the description carries the full disclosure burden. It does well on two fronts — the exact return shape (concept, unit, value, start, end, fy, fp, form, filed) and the tier-based 12-month limitation on results. It stops short of covering pagination/row limits or the fact that many concepts may be absent for a given filing.

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 sentences, front-loaded with the resource and return columns, then narrowing behavior, then the sibling alternative and tier caveat. Every clause carries information; nothing is redundant padding.

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?

With no output schema, the description compensates by naming the returned columns, and it covers the concept filter and the free-tier scope limit. It is nearly complete for a two-parameter read tool, missing only result-volume/pagination expectations.

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%, so the description must compensate, and it does for the ambiguous parameter: 'concept' is explained as a single us-gaap concept with three concrete example tags (NetIncomeLoss, Assets, RevenueFromContractWithCustomerExcludingAssessedTax). 'ticker' is left implicit as an obvious company identifier, with no format guidance.

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?

States a specific verb+resource ('Raw SEC XBRL facts a company reported in its 10-K/10-Q filings'), enumerates the returned columns, and explicitly distinguishes itself from the sibling financial_statements. An agent can tell instantly that this is the raw-fact tool rather than the derived-statement tool.

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?

Gives both directions of routing: use this tool for raw facts, optionally narrowed by concept; 'For ready-made income statements, balance sheets and cash flows use financial_statements instead.' It also adds a scope caveat (free tier returns only the last 12 months), which affects tool selection.

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