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

Annotations already declare readOnlyHint: true, destructiveHint: false, and idempotentHint: true. The description adds beyond this: 'Read-only, cached for up to an hour' and the crucial access requirement (agent token, otherwise returns setup steps). It also discloses the paging contract via the `total` field and the row structure, which is not in annotations. No contradiction with annotations.

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 purpose and usage, then details row content, paging, and access. Each sentence earns its place: no filler, no repetition. The structure is logical and the length is justified given the lack of an output schema and the need to explain filtering and paging. It is concise relative to the information it conveys.

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?

Since there is no output schema, the description must fully specify what the tool returns. It lists every row field (ticker, asset name, transaction type, dates, STOCK Act status, amount range, owner, member, and link) and explains the `total` field for pagination. It also covers access requirements and caching. Nothing an agent needs to call and interpret the result 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 coverage is 100%, so the baseline is 3, but the description adds substantial semantic value: it explains the offset/limit paging pattern ('keep raising offset by limit until you reach total'), how to combine ticker and member_id for a single member's trades in one stock, and that 'neither' returns every trade. It also clarifies that ticker is case-insensitive (also in schema, but reinforced). This goes well beyond the schema's individual parameter descriptions.

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 opens with a clear statement of the resource ('Individual disclosed congressional stock trades') and ordering ('newest disclosure first'), then explicitly labels itself 'The paging tool' and contrasts it with get_member and get_stock, which only return 20 recent trades. This makes the tool's purpose unmistakable and distinguishes it from siblings without reading their schemas.

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 an explicit condition: 'use it when get_member or get_stock's 20 most recent trades are not enough, or to walk the whole record.' It also describes the four filtering modes (ticker, member_id, both, neither), which tells the agent exactly when to use each variant. No other sibling is mentioned as an alternative, but the primary decision rule is clear.

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