Coldpine: Congressional Stock Disclosures

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

Beyond annotations (read-only, idempotent, non-destructive), the description adds materially: authentication via Bearer token and the failure mode without it (setup steps), caching for an hour, rolling window anchored to latest trade date, ordering, per-person deduplication, and the coordination caveat. 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 a dense but well-ordered paragraph: definition, output, usage, key behavioral constraints, and access. Every sentence carries information needed for correct invocation or interpretation; there is no filler or repetition of schema defaults.

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 names all returned components (ticker, direction, member count, trade count, date span, amount range, member names). It also covers auth, error behavior, caching, and data interpretation, so an agent has enough context to call and understand the result.

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 per-parameter basics are already documented. The description adds meaning beyond the schema by explaining that window_days counts back from the most recent trade date on record, that people are counted once per cluster regardless of trade count, and that ordering is by distinct member count.

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 precise definition: stocks several members of Congress traded in the same direction inside a rolling window, and enumerates the returned fields. It also names the sibling get_stock as the alternative for single-stock queries, making the tool's scope unmistakable.

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?

It gives an explicit usage frame ('what are several members buying (or selling) at once') and names the specific alternative and its condition: for everyone who ever traded one given stock, use get_stock. That is direct when-to-use/when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavior: read-only and cached for up to an hour, requires auth token, and returns setup steps if unauth'd. It also lists the output fields, going beyond annotation coverage. No contradictions 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, then delivers metrics, filters, alternatives, and access details in a logical order. Every sentence contributes: the data-source reference, use case, output fields, and exclusion alternatives all earn their place. No fluff.

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?

For a filtered ranking tool with no output schema, the description is complete: it specifies all parameters, output fields, auth requirements, caching behavior, and sibling alternatives. Nothing an agent needs to call it 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 every parameter is already documented. The description restates some parameter meanings (e.g., volume as sum of amount-range midpoints) but adds no new semantics beyond what the schema provides. Baseline 3 is appropriate since the schema carries the full burden.

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 clear verb ('ranked') and resource ('Members of Congress'), enumerates the ranking metrics (trade count, volume, average size, disclosure speed), and immediately distinguishes itself from siblings by naming the data source and providing a canonical use case. It also lists specific parameters (chamber, party filters), making the tool's scope unmistakable.

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 states when to use: "Use it for 'who trades the most in Congress' style questions." Then contrasts with siblings: "For returns against the S&P 500 use members_vs_market, and for late filing use stock_act_compliance." Also covers access prerequisites (token) and behavior without it, giving full usage context.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds meaningful behavioral context: unknown ids produce a not-found error, missing authentication returns setup steps, and results are cached for up to an hour. This goes beyond what the annotations convey.

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 dense but well structured: return contents first, then usage context, then access/caching behavior. The first sentence is long and comma-heavy, which slightly reduces scannability, but every part earns its place and there is no filler.

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 carries the burden of explaining the return value, and it thoroughly covers filer identity, roll-up numbers, trades, document link, and the sample trade. It also covers error, auth, and caching behavior, leaving an agent with everything needed to invoke and interpret the call.

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?

The single parameter `filing_id` is already fully documented in the schema, including its constraints, format, and where it comes from. The description reinforces that origin context but does not add new parameter-level meaning, so a baseline of 3 is appropriate at 100% schema coverage.

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 exactly what the tool returns: a single STOCK Act Periodic Transaction Report with filer details, roll-up statistics, all disclosed trades, the original document link, and the sample scored trade. The title and description clearly distinguish it from broader listing/summary sibling 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 to use it after whats_new, list_recent_filings, or get_member has provided a filing id, and that the question must be about what that one report contained. This gives clear when-to-use guidance and routes the agent away from list-level alternatives.

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

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

Annotations already mark the call as read-only, idempotent, and non-destructive, and the description adds valuable behavior beyond that: caching up to an hour, not-found errors for unknown ids, and the fact that an unauthorized call returns setup steps instead of data. 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 dense but every clause earns its place: return contents, usage context, sibling routing, error behavior, auth, and caching. It is front-loaded with the main resource and use case before moving into operational 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?

There is no output schema, but the description fully compensates by enumerating every return component, the data limit, the error case, the auth requirement, and the cache policy. An agent has everything needed to call and interpret this tool correctly.

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% and the single member_id parameter is already documented in the schema. The description adds meaning by telling the agent where to find this id, such as from search_members or any coldpine.io/politicians URL, which improves selection and invocation confidence.

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 exact resource (one member of Congress) and enumerates the returned components: profile, aggregate stats, recent trades, transaction reports, and sample scored trade. It also gives a direct use case, 'what has this member been trading', which distinguishes it from sibling tools like list_transactions and get_filing.

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?

It explicitly tells the agent to obtain member_id from search_members first, and directs it to list_transactions when more than 20 trades are needed. It also covers authentication requirements and error behavior, so the when-to-use and alternatives are unambiguous.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds concrete behavioral details: the tool is cached for up to an hour, requires no authentication, returns a not-found error for untraded symbols, and provides sample output content such as source-filing links. This is exactly the kind of context annotations cannot convey.

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 detailed but every sentence carries distinct value: output contents, canonical use case, sibling alternatives, error behavior, and access/caching. It is well organized and avoids filler while remaining front-loaded with the most decision-relevant information.

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 fully enumerates what the tool returns, specifies error behavior, names alternatives, and covers access and freshness. For a single-parameter read-only tool, nothing needed for correct invocation or interpretation 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% and the single parameter is already well-documented with format constraints, case-insensitivity, and an example. The description only repeats 'ticker' and does not add meaningful parameter semantics beyond the schema, so the baseline score 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?

The description clearly states the tool returns aggregated congressional trading data for a single ticker: totals, buy/sell split, dates, top traders, and recent trades. It explicitly frames the use case as "who in Congress trades this stock" and distinguishes itself from list_transactions and cluster_trades, making its purpose unambiguous.

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?

It gives explicit guidance: use this for 'who in Congress trades this stock', use list_transactions for full trade history, and use cluster_trades for coordinated trades. It also notes the not-found error condition and that no key or account is needed, leaving little to inference.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses caching ('cached for up to an hour'), authentication behavior ('without it the call returns setup steps instead of data'), pagination behavior (25 per page, page past end empty), and the `coverage` field for total counts. It also explicitly says 'Read-only', reinforcing the annotations. No contradictions.

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 compact and logically ordered: purpose, then how to use (coverage), then explicit alternatives, then access requirements. Every sentence carries useful information; there is no filler or redundancy. Though a bit long, it earns its length with high information density.

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?

For a single-parameter paginated list tool, the description is complete: it covers output fields, pagination semantics, coverage/totals, caching, token requirements, and sibling routing. The annotations cover safety (read-only, idempotent, non-destructive) and the schema covers the only parameter, so nothing an agent needs to call it 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?

The input schema already fully documents the `page` parameter (type, default, min/max, description covering pagination and empty-list behavior). The description repeats '25 per page' and 'newest filed date first', which are already in the schema, and adds no new meaning about the parameter itself. Baseline 3 is appropriate given 100% schema coverage.

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 exactly what the tool does: lists the newest Periodic Transaction Reports with parsed trades, newest filed date first, 25 per page, and enumerates the fields returned. It explicitly distinguishes itself from siblings like whats_new and get_filing, so an agent can immediately tell it apart.

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?

It gives explicit when-to-use guidance: 'Use it to browse the archive of reports page by page', and clarifies alternatives: 'whats_new is lighter and needs no token' for latest reports/polling, and 'get_filing' for trades inside a report. Also notes the token requirement and what happens without it. This is unambiguous routing.

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

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.

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

Beyond the annotations' read-only/idempotent/destructive hints, the description discloses that the data is cached for up to an hour, requires an Authorization Bearer token (and returns setup steps without it), returns rows in descending 90-day alpha order, and only covers disclosed purchases with a full 90-day window. It also explicitly warns it is not a forecast. This is substantial added behavioral context.

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 a single dense paragraph, but it front-loads the core purpose and flows through eligibility, usage, output order, method, disclaimers, auth, and caching. Every sentence adds operational detail; however, the breadth of topics makes it less scannable than a bulleted structure, though it remains efficient.

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 lists every field that will appear in each row (number of purchases, average 90-day return, S&P average, 90-day and 30-day alpha, hit rate, member page) and states the response will describe the method. It also covers eligibility, exclusions, auth failure mode, and cache lifetime. Given the tool's two simple optional parameters, the description is fully adequate for correct invocation.

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?

Since the input schema already documents both limit and min_trades with 100% coverage, the baseline is 3. The description adds one meaningful constraint: members must have min_trades priced purchases that have a full 90-day window, which clarifies the window requirement not present in the schema. It does not add new information about limit, but the min_trades clarification warrants a 4.

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 the exact computation—per-member 90-day return on disclosed stock purchases versus the S&P 500, including 30-day alpha and hit rate—so the agent knows the resource and metric. It further distinguishes this tool from congress_leaderboard by stating that the latter ranks activity and carries no returns. This makes the purpose unambiguous and separated from siblings.

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 tool explicitly states 'Use it when the question is about performance' and contrasts congress_leaderboard as the activity-ranking tool without returns. This gives the agent both a positive trigger and an explicit alternative, covering the when/when-not distinction. It does not reference the other eight siblings, but the performance/activity split is the key decision point.

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

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

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds new behavioral context: the tool is read-only, cached for up to an hour, requires no key or account, and total_matches signals truncation by limit. This goes beyond what annotations provide and helps the agent understand response semantics and freshness. No contradictions 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 four sentences, each carrying distinct value: purpose, usage context, return fields and truncation signal, alternative tool, and access/caching note. It is front-loaded with purpose and usage, and no sentence is redundant with the schema or annotations. It is dense yet concise, earning a 5.

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?

Given there is no output schema, the description compensates by listing the return fields (name, chamber, party, state, trade and filing counts, buy/sell split, dollar volume range, coldpine.io page) and explaining total_matches. It also covers access requirements and caching. For a search tool with 3 parameters and no output schema, this is fully sufficient for an agent to invoke it correctly and interpret results.

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% (all three parameters have descriptions in the schema). The description adds minimal parameter-specific meaning: it reiterates the query is by 'full or partial name' (already in schema) and implies limit affects total_matches, but does not explain limit/chamber beyond the schema. At 100% coverage, a baseline of 3 is appropriate; the description adds little incremental parameter clarity.

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 specific verb and resource: 'Find members of the U.S. House or Senate who have disclosed stock trades, by full or partial name.' It clearly states the tool's function and explicitly distinguishes it from siblings by noting it returns member_id used by get_member and list_transactions, and pointing to congress_leaderboard for ranking. This leaves no ambiguity about what the tool does or how it differs from related 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?

The description gives explicit when-to-use guidance: 'Start here whenever a question names a person' and explains the output feeds other tools. It also states when NOT to use it: 'To rank all members rather than look one up, use congress_leaderboard.' This directly addresses both positive and negative usage cases, which is exemplary.

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

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

Despite annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds meaningful behavioral context: it requires an Authorization Bearer token and returns setup steps without it, is cached for up to an hour, and returns the site-wide summary on every call regardless of sort. It also provides an important interpretive caveat that a late report is a fact about filing date, not a finding of wrongdoing. This goes well beyond what annotations convey.

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 long but every sentence carries useful information: output contents, the avg_lag_excess caveat, usage guidance, alternative tools, access requirements, and data freshness. It is front-loaded with the core behavior and then branches into caveats and access. A minor structural improvement would be separating the auth/access sentence from the output discussion, but nothing is wasted.

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?

For a tool with no output schema, this description is remarkably complete: it names the returned components (site-wide summary and per-member board), specifics of the member board fields, the excess-return caveat, source parity, access method, fallback behavior without a token, caching behavior, and how to get more granular member lag data. An agent has enough to correctly invoke and interpret the tool without supplemental documentation.

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% with detailed descriptions for sort and limit, so the baseline is 3. The description adds value by explaining that the site-wide summary comes back on every call whatever the sort, which affects how the sort parameter should be interpreted. It also clarifies the sort ranking is always highest first via the schema, and the description's metric name explanations align with the enum values. This extra context justifies a score above baseline.

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?

Description states a precise purpose: measuring how quickly Congress reports trades against the STOCK Act's 45-day window, with both a site-wide summary and per-member board. It clearly distinguishes itself from siblings by pointing to get_member/list_transactions for individual trade lag, and notes the same data source as coldpine.io. The verb 'reports' and the specific metrics (median lag, share late, House vs Senate) make the tool's scope unambiguous.

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 states when to use this tool ('who files late' and 'how late is Congress overall') and when not to use it (for one member's lag, read disclosure_lag_days in get_member or list_transactions). It also warns about the avg_lag_excess metric never being quoted without the S&P 500 comparison, which is a usage constraint an agent needs to act on. This is strong routing guidance beyond any schema.

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

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.