Coldpine: Congressional Stock Disclosures

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

With no annotations provided, the description carries the burden of establishing the operation's profile. It does so by framing it as a read-only analytical query ('Returns...') and by giving the output fields, so an agent can see it is non-mutating. It does not mention ordering or the exact clustering threshold, but no side effects or hidden mutations are implied.

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?

Two dense sentences plus a source reference, with no filler. The core definition is front-loaded, and the returned fields are listed concisely. Every sentence adds useful 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?

For a 4-parameter tool with no output schema and no annotations, the description is reasonably complete but has gaps. It states the query concept, the output fields, and the data source, but it does not explain how `limit`, `min_members`, and `window_days` interact, nor what ordering the results use. These missing details matter because neither the schema nor annotations supply them.

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 0%, so the description must compensate for parameter meaning. It partially does: 'same direction' maps to `direction`, 'rolling window' maps to `window_days`, and 'several members' maps to `min_members`. However, `limit` is never mentioned, and the parameter mappings are vague enough that an agent could not confidently set exact values without inspecting the 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 opens with a specific and non-tautological definition: 'Stocks that several members of Congress traded in the same direction inside a rolling window,' then enumerates the exact returned fields. This clearly differentiates it from sibling listing/filing tools such as list_transactions and search_members.

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 implies the use case—finding correlated congressional trades—but never states when to prefer this tool over siblings or when not to use it. The references to 'the bot' and the coldpine.io page provide context but no explicit alternative routing or exclusion criteria.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, any side effects, data freshness, pagination, or the shape of the returned data. The mention of 'same data' is a source reference, not a behavioral trait.

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?

Two concise sentences that front-load the core function (ranking members) and list the key options without redundancy. Every clause adds value, and the external reference is a single short clause.

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 no output schema, the description should explain what the response contains (e.g., member names, stats, ordering) and how limit/filters affect results. It does not mention return format or the behavior of the limit parameter, though the defaults and enums in the schema help. It is adequate for a simple list but lacks detail on output and usage context relative to siblings.

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 description adds meaning to the sort parameter by explaining each enum value (trade count, volume as sum of amount-range midpoints, average size, speed). It also confirms chamber and party are filters, though the schema already documents chamber's enum. With only 25% schema coverage, the description compensates well for the sort values.

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 a ranking of members of Congress by disclosed trading activity, with explicit sort options (trade count, volume, average size, speed) and optional chamber/party filters. It distinguishes itself from siblings that focus on individual filings or members, though it does not name them explicitly.

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 implies this is for leaderboard/overview data (e.g., 'ranked by'), but it does not explicitly state when to use it versus alternatives like members_vs_market or search_members, nor does it provide exclusions. The 'Same data as coldpine.io/leaderboard' is external and not a sibling comparison.

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?

With no annotations, the description carries the burden and does disclose what the returned report contains, including the roll-up fields, all disclosed trades, original document link, and the sample scored trade. It does not discuss errors, authentication, or freshness, which prevents a higher score, but the content inventory is substantive.

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 one dense sentence that front-loads the object and then uses a colon-structured list of contents. Every clause contributes useful information, though the run-on style and heavy comma usage keep it from being maximally clean.

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, so the description supplies a thorough inventory of the return value: filer identity, filing date, roll-up stats, every trade, source link, and the sample scored trade. It omits edge-case behavior for unknown filing_id, but with a single well-documented parameter this is a minor gap.

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%, and the filing_id parameter is already well documented with type, bounds, and a source hint (from coldpine URLs, list_recent_filings, or get_member). The description adds no parameter-specific meaning beyond what the schema provides, so the 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?

The description identifies the resource as a single STOCK Act Periodic Transaction Report and enumerates its contents: filer info, roll-up statistics, trades, source link, and sample scored trade. This is far from a tautology and the word 'single' helps distinguish it from list-style siblings like list_recent_filings, though it does not explicitly name an alternative.

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?

There is no when-to-use or when-not-to-use guidance in the description, and no mention of alternatives such as list_recent_filings or get_member. The only contextual hint lives in the parameter schema, not the description, so an agent gets no explicit routing help.

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?

No annotations are provided, so behavioral disclosure falls entirely on the description. It transparently describes what data is returned, including the '20 most recent disclosed trades' and 'one sample scored trade the public page shows,' but it does not mention side effects, permissions, data freshness, or rate limits. The read-only nature is only implied by the name and content.

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 sentence that front-loads the core scope ('One member of Congress') and then efficiently lists specific return components. It is compact but slightly run-on, with several parenthetical elaborations packed into one clause.

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 is the primary source of return-value information. It covers the major components an agent would need to know about: profile, stats, recent trades, filing links, PTRs, and a sample scored trade. It does not describe formatting or error behavior, but it is sufficiently complete for a simple get-by-id tool.

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 schema fully documents the only parameter, member_id, including its source and format. The description adds no parameter-level meaning, but schema coverage is 100%, so the baseline of 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?

The description states the tool returns data for exactly one member of Congress and enumerates specific contents: profile, aggregate trading statistics, 20 recent trades with filing links, recent Periodic Transaction Reports, and a sample scored trade. This clearly distinguishes it from sibling tools like search_members or list_transactions.

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?

Usage is implied through 'One member of Congress' and the detailed list of returned data, but there is no explicit guidance about when to use this instead of siblings such as get_filing, list_transactions, or search_members. The schema does mention where to obtain member_id, which helps, but the description itself does not provide alternatives or exclusions.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly lists what the tool returns, which is transparent about output, but it does not mention any side effects, limitations (e.g., valid ticker requirements, empty results), or performance characteristics. It is a read-only query by nature, but that is not explicitly stated, so the disclosure is adequate but not rich.

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 long run-on sentence that packs many output components. While it is front-loaded with the core purpose, the listing is cumbersome and would benefit from bullet points or separate sentences. It is not concise, but it contains no filler; every clause adds information, so it is not overly verbose.

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?

The description lists all expected return items in detail, which is sufficient for an agent to know what to expect. It does not mention error conditions or how to handle missing data, but given the simple one-parameter interface and the absence of an output schema, it covers the essential information an agent needs to call the 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?

The input schema has 100% coverage for the single parameter 'ticker' with a description 'Stock symbol, e.g. NVDA.' The tool description adds no additional meaning about the parameter, such as formatting rules or validation. Per the baseline, since schema coverage is high, a 3 is appropriate.

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 verb 'get' and the resource 'stock', and enumerates a specific list of outputs (totals, buy/sell split, date ranges, top members, recent trades with links, sample scored trade). This distinguishes it from sibling tools like list_transactions (raw transactions) and get_member (single member), making its purpose 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?

The description makes it obvious this tool is for a single ticker's aggregated congressional trading summary, but it does not explicitly name alternatives or state when to prefer this over list_transactions or get_filing. The context is clear enough that an agent would know to use it for per-stock overviews, but there is no direct exclusion 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?

With no annotations, the description carries the behavioral burden and does disclose meaningful details: sort order (newest filed date first), page size (25), and parsed fields plus the late-trade metric. This goes well beyond a bare action statement, though it does not address auth or rate-limit behavior.

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 sentence front-loads the core resource and ordering, then lists fields and the external reference. Every clause adds information, though the sentence is long and packed.

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 simple one-parameter paginated list with no output schema, the description is largely complete: it states what is returned, how results are ordered, page size, and the key fields. It could mention response envelope or failure modes, but nothing critical for invoking 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 schema has 0% description coverage for the single page parameter, so the description must compensate. It adds the '25 per page' pagination context and ordering, but it never explicitly explains how the page parameter maps to pages or what higher page values return.

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 identifies the resource (newest Periodic Transaction Reports / STOCK Act filings) and enumerates the fields returned, including late-trade counts. It lacks an explicit imperative verb, but the name and title carry the 'list' action, and the scope is specific enough to distinguish filings from transaction-level 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?

No guidance is given about when to choose this tool over siblings such as get_filing, get_stock, or list_transactions. The description implies a recent-filings browsing use case but never states exclusions or 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?

With no annotations, the description carries the behavioral burden. It discloses the ordering (newest disclosure first), pagination behavior (limit up to 50, offset), optional filtering, and that each row links to the original filing document. It does not mention rate limits or authentication, but those are not obviously critical for this read-style list endpoint.

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?

Two sentences, no filler. The core resource and ordering are front-loaded, followed by filtering, pagination, and per-row provenance information. Every sentence earns its place.

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 list endpoint with four optional parameters, the description is largely complete: it covers scope, ordering, filters, pagination, and row content links. Since there is no output schema, it could have added more detail about returned fields, but the existing description is enough for an agent to select and invoke the 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 description coverage is 0%, so the description must compensate. It does so by explaining ticker and/or member_id as filters and by noting limit and offset for pagination. It does not state defaults or value formats, but the schema already encodes the numerical bounds and the parameter names are self-explanatory.

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 specific verb and resource: disclosed congressional stock trades, newest disclosure first, with optional ticker and member_id filtering. It also adds concrete details like pagination and source links, which clearly differentiates it from sibling listing 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 clear usage context: list trades when you want disclosed congressional stock transactions, optionally filtered by ticker or member_id, with pagination. It does not explicitly name alternatives or exclusions, but the filter and pagination details make the intended use obvious.

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?

With no annotations, the description carries the full behavioral burden. It discloses the filtering behavior, the calculation windows, and even the likely outcome ('Most members do not beat the market'), which gives useful context beyond the bare schema.

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 concise and efficiently front-loaded with the core metric. Every sentence adds value, and the external data source link is a useful reference without bloating the text.

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 and no annotations, the description covers the main calculation, qualifying criteria, interpretation, and data source. It is nearly complete, though it omits ordering, pagination, or what limit controls, which prevents a 5.

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 0%, so the description must compensate. It does explain min_trades ('members with at least min_trades priced purchases'), adding real meaning, but limit is left unexplained despite also being relevant to output size.

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 specific analytical goal: computing per-member 90-day returns versus the S&P 500, plus 30-day alpha and hit rate. This clearly differentiates the tool from sibling list/filing tools and identifies the resource and metrics it produces.

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 implies when to use it (when you need per-member alpha versus the market) and gives qualifying criteria (min_trades, full 90-day window). However, it does not explicitly mention alternatives or say when not to use it compared to sibling tools.

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?

With no annotations, the description carries the transparency burden. It usefully discloses output components (trade/filing counts, buy/sell split, volume range, coldpine.io page), but it does not state whether this is read-only, how limit affects results, or behavior for no matches. These gaps prevent a fully transparent picture.

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?

Two tight sentences: the first states purpose and matching mode, the second lists return values. Every word contributes, and there is no 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?

For a 3-param search tool with no output schema or annotations, the description is adequate but incomplete. It explains main outputs and the name-search use case, but it lacks explicit alternative routing, limit behavior, and a fuller return-shape description, so an agent may still be unsure about edge cases.

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 33%, so the description needs to compensate. It clarifies that query is a partial name and hints at chamber via 'House or Senate', but it says nothing about limit's semantics beyond the schema's default/max. The description adds some meaning but does not fully cover the undocumented parameters.

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 names a specific action ('Find members ... by (partial) name'), a precise resource (U.S. House or Senate members with disclosed stock trades), and the returned data. This differentiates it from singular 'get_member' and other sibling tools, so an agent can recognize what it does without opening the schema.

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 intended use is implied: search by partial name when you need a member's trade/filing summary. But there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives like get_member for exact member lookup, so the agent must infer 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?

With no annotations, the description carries the full behavioral disclosure burden. It does disclose an important behavioral constraint: avg_lag_excess is only shown when a member has at least 5 priced purchases, and it instructs never to quote it without the S&P 500 move. However, it does not state whether this is a read-only operation, mention rate limits, or clarify how the data is returned beyond high-level content.

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 relatively compact and front-loaded with the core purpose, then adds a conditional-data caveat and a source reference. The parenthetical lists are dense but useful. The 'Same data as coldpine.io/...' sentence adds a reference point but is not necessary for tool invocation, keeping it from being a perfect 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 and no annotations, the description does a solid job of outlining what the agent will get: a site-wide summary, a per-member board, and the conditional avg_lag_excess metric. The main gap is that it does not explain how `sort` and `limit` shape the results, but for a 2-parameter tool the overall picture is reasonably 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?

The input schema has 0% description coverage, so the description must compensate by explaining the parameters. It does not mention `sort` or `limit` at all. The description's mention of metrics like 'trades past 45 and 90 days' and 'median lag' implicitly maps to some enum values, but that connection is left for the agent to infer rather than explicitly explained.

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's purpose: it reports how quickly Congress discloses trades relative to the STOCK Act's 45-day window, covering both site-wide summaries and per-member boards. It mentions specific metrics and the conditional avg_lag_excess field, making the purpose clear. However, it does not explicitly differentiate itself from sibling tools such as congress_leaderboard or members_vs_market.

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?

There is no guidance on when to choose this tool over its siblings, no exclusions, and no comparison to alternatives. The description only provides details about what the tool returns and references an external data source, but never tells the agent 'use this when...' or 'use that instead when...'.

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?

With no annotations, the description carries the full burden, and it conveys key behavior: newest-first ordering, the fields included per filing, and the date-filter semantics. It does not describe pagination or response envelope, but for a read-style listing tool the behavior is largely transparent.

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?

Two sentences with no filler: the first front-loads the resource, ordering, and returned fields, and the second adds the filtering usage. Every clause contributes useful 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?

For a low-complexity tool with two optional parameters and no output schema, the description covers the core return contents, ordering, and main filter. It could be more explicit about limit behavior or response shape, but the schema already provides reasonable defaults.

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 description explains `since` with format and intent, but the schema already provides the same after-date semantics. The `limit` parameter gets no description-level treatment beyond its schema default/max/min, and at 50% schema coverage the description doesn't fully compensate for that 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 identifies a specific resource ('newest Periodic Transaction Reports'), a clear ordering ('newest first'), and enumerates the included fields such as buy/sell mix, tickers, and late-filing flag. This is a concrete verb-plus-resource statement that helps differentiate it from siblings like list_recent_filings.

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 explicitly states the polling use case ('built for agents that poll') and explains when to pass `since` to get filings after a date. It does not explicitly mention when to prefer a sibling tool instead, so it stops short of full alternative guidance.

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