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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description goes beyond these by adding caching behavior ('cached for up to an hour'), access requirements ('no key or account needed'), and a scope limit ('Looks at the 100 most recent reports'). These are valuable contextual behaviors not present in structured fields.

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?

A single, dense paragraph that front-loads the primary purpose and immediately explains the `since` usage. Every sentence contributes: purpose, filtering, return details, alternatives, access, and caching. Slightly long but efficient—no filler or redundancy.

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?

Even without an output schema, the description enumerates the returned fields comprehensively (filing_id, member details, trade counts, etc.). It covers access requirements, caching, scope limit, and routes to sibling tools for adjacent needs. For a simple two-optional-parameter read-only tool, this is complete.

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 baseline is 3, but the description adds semantic value to the `since` parameter by framing it as a polling mechanism ('pass `since` (YYYY-MM-DD) to get only reports filed after that date'). It also clarifies that omitting `since` returns the latest 25, which aligns with the schema default but is explicitly stated. This enriches the agent's understanding beyond the raw schema.

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 the tool lists the newest STOCK Act Periodic Transaction Reports, newest first, and gives a concrete use case ('what did Congress just disclose'). It distinguishes itself from siblings by explicitly naming list_recent_filings for older reports and get_filing for trade-level details, so an agent can select it without opening other tools.

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?

Explicitly says when to use this tool (answer recent disclosure questions, poll for new filings) and when to use alternatives ('for older ones page through list_recent_filings, and for the trades inside one report call get_filing'). It also explains the `since` parameter as a mechanism for polling, providing clear guidance.

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