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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the read-only/safe nature is covered. The description adds value by clarifying this returns 'reported' transactions (data source) and specifying filter dimensions. It doesn't describe pagination via cursor beyond the schema, but with rich annotations the bar is appropriately lower.

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 compact sentence that names the resource, the action, and the key filter dimensions. Zero filler or repetition. Ideal front-loaded structure for a query tool.

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?

This is a moderately complex read-only query tool with 8 parameters, a solid schema, and clear annotations plus an output schema. The description covers the primary use case and filter dimensions. It could add how 'days' interacts with explicit date windows and mention pagination patterns, but given the strong schema and annotations, the description is reasonably complete for its purpose.

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 only 25%, meaning most of the 8 parameters aren't documented in the description. The description mentions ticker, member, asset owner, and transaction dates as filter options, which loosely maps to symbols, member_names, asset_owner, and start_day/end_day. However, it doesn't explain the relationship between 'days' and 'start_day/end_day', nor that 'cursor' is for pagination (though the schema covers that). With 25% coverage, the description partially compensates but doesn't fully bridge the gap.

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 uses a specific verb-resource structure ('Return reported United States congressional transactions') and lists concrete filters (ticker, member, asset owner, dates). It clearly identifies what the tool returns. It's distinguished from 'politics_us_congress_aggregate' by implying this returns individual transactions rather than aggregated data, though it doesn't explicitly contrast with that sibling.

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 states filters that can be applied, implying usage for looking up transactions by ticker, member, owner, or dates. However, it doesn't explicitly state when to use this vs. politics_us_congress_aggregate, nor give examples or mention the days lookback default. The usage context is implied but no explicit when-not guidance is given.

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