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

Annotations only cover read-only/idempotent/no-destructive safety; the description adds substantial behavioral context beyond that: counts are as-filed and never split-adjusted, rows are ordered oldest-first, one row per class and as-of date, coverage starts in 2009 and only for XBRL-tagged filers, 20-F/40-F filers yield roughly annual windows, filer errors are returned as filed, and split listing depends on a subsequent restatement. That is exactly the kind of non-obvious behavior an agent needs before trusting the output.

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 purpose is front-loaded, but the body is a single dense block of edge-case prose (split detection heuristics, 1000x tag corrections, combined ratios, multi-class member names, 2020 Apple example) with no bullets or grouping, so key calling information competes with domain trivia. Much of it is valuable, but the agent must read the whole wall of text to extract the routing decision.

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 domain-specific historical-data tool this is thorough: it covers coverage window, ordering, multi-class naming, the 'listed' ticker mapping, as-filed fidelity, and error passthrough, and it explains the returned split/restatement fields. With an output schema present, that return-value detail is redundant but nothing an agent needs in order to call it correctly 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?

Schema description coverage is 0%, so the description must carry the burden, and it supplies a brief Args section: CIK with an example, share_class 'as returned in share_class', from_date with YYYY-MM-DD format, to_date as 'Latest as-of date'. This clarifies that filtering is on as-of date rather than filing date, which the schema does not, but it omits the null defaults, gives no format hint for to_date, and the share_class phrasing is self-referential and circular.

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 first sentence names a specific verb and resource (share counts over time) and pins the exact data source (cover page of 10-K/10-Q/20-F/40-F, dei:EntityCommonStockSharesOutstanding). It also differentiates from the general filing-reading siblings by stating 'Use this for share-count history, dilution, buybacks and splits instead of reading filings one by one.' No ambiguity about what is returned or where it comes from.

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 enumerates the use cases (share-count history, dilution, buybacks, splits) and tells the agent not to read filings one by one, plus a diagnostic rule: 'a ratio_to_previous far from 1 with no split listed is worth checking in the filing.' However, it never names a concrete sibling tool (e.g. get_financial_history or verify_figure) as an alternative for the same question, so routing is implied rather than explicit.

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