Inspect or extend the disclosure index

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

Adds substantial behavior beyond the annotations: the upstream site is rate-limited, each call is capped and resumable, already-indexed reports are never refetched because filings are immutable, and clients time out at 60 seconds. It also quantifies archive size (~180/690/~2,400 reports) so the agent can plan repeated calls. The 'extends local index' framing is consistent with readOnlyHint=false.

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?

Front-loads the purpose and mode switch in the first sentence, then layers operational detail economically. The 'Rough sizes' sentence is useful planning data rather than padding, though the resumability point is touched twice (once as mechanics, once as 'each call reports how many reports remain').

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 still covers what a call returns ('each call reports how many reports remain'), how to resume, why calls are capped, and how many calls deep history will take. Nothing an agent needs to invoke this 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 100%, so the schema already carries both parameters and their bounds. The description reinforces the omit-vs-pass semantics of sinceDays and the per-call cap rationale, but adds little that the schema does not already state; baseline 3 applies.

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 dual purpose with concrete verbs and resource: 'Show how much Senate disclosure history is indexed locally, and extend it.' The 'Senate'/'indexed locally' scope implicitly separates it from House-filing and trade-query siblings, but no sibling is named explicitly, so it falls short of full differentiation.

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 precise mode selection: 'Call with no arguments to report coverage; pass sinceDays to backfill,' and sets expectations with 'Expect to call this several times to build deep history.' It lacks any explicit pointer to the alternatives an agent might reach for (e.g. congress_trades to read the data rather than index it).

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