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

Beyond the readOnly, openWorld, idempotent, and non-destructive annotations, the description discloses that only nonzero published records are returned, that omitted dates are not filled with inferred zeros, and that observations should not be summed as daily flow. It also adds context about the bounded hot window and provenance fields, which materially shapes the caller's expectations.

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 front-loaded with the essential action and result, then gives concrete use examples, and then adds one important interpretational caveat. Every sentence earns its place and there is no filler or repetition of the schema details.

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 helpfully enumerates the shape of the response as settlement dates, quantities, SEC price fields, source-row counts, pagination, and provenance. It is still slightly incomplete because it does not state output ordering, the exact behavior when a date has no nonzero records, or how the hot window is defined, which an agent may need to know without a JSON output schema.

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 100%, so the description does not need to restate parameters and the baseline is 3. It reinforces the meaning of pagination and date-bounded behavior but does not add meaningful per-parameter details beyond what the schema already provides.

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 states a very specific verb-and-resource pair: returning a bounded, paginated history of published nonzero SEC fails-to-deliver records for one ticker in the self-hosted hot window. It also scopes the tool away from sibling sec_ftd_* tools by emphasizing a single-symbol, time-series history rather than latest, comparison, search, or top-level aggregates.

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?

The description gives explicit use-case examples such as 'show GME FTD balances over time' and 'chart TSLA published fail balances this quarter', which is strong usage guidance. It does not explicitly name sibling tools like sec_ftd_latest or sec_ftd_compare as alternatives, nor does it explain when not to use this tool in favor of them, so it stops one level short of a fully explicit routing guide.

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