Insider Buy Signals

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

Annotations already declare readOnly=true, destructive=false, idempotent=true, openWorld=false, so safety is covered. The description adds genuinely non-obvious behavior beyond them: default page size of 25, intent-strength sort tiebreak, total_matched reporting, and the notable data-quality rule that 'filings without a source link are dropped'.

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?

Purpose is front-loaded, then sort order, then defaults/paging, then filters, then the drop rule. Every clause carries information and none is padding, though the single dense sentence spanning paging and filters is slightly overloaded for skimming.

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 discloses the shape of the response (newest-first rows, total_matched, per-stake filing_url) and the paging contract. All five parameters are addressed and the drop rule is surfaced, so nothing needed to call or interpret 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 the baseline is 3. The description reinforces rather than repeats: it restates the 25-row default, the limit/offset paging model, total_matched, and frames min_percent as a percent-of-class floor, adding light interpretive value on top of 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?

States a specific resource and scope: 'Recent activist Schedule 13D / 13D-A filings on US-listed companies', with a defined sort order. An agent immediately knows this is a recency list of activist filings, but the description never names the obvious sibling verify_activist_13d, so the boundary between 'list recent' and 'verify a specific filing' is left to inference.

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 by 'Recent ... filings' plus the optional filters (min_percent, ticker, days), which gives an agent enough to know when it applies. However there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as verify_activist_13d or the insider/13F siblings.

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 readOnly/idempotent/non-destructive. The description adds real behavioral context beyond them: newest-first ordering, default page size, pagination contract via total_matched, limit<=0 meaning no cap, and the non-obvious filtering rule that awards without a source link are silently dropped and never returned.

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?

Three compact sentences, front-loaded with what the tool returns and then the paging/filtering behavior. Every clause carries information; nothing is padding.

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?

No output schema exists, so the description compensates by naming the key response fields (total_matched, award_url) and disclosing the drop rule for awards lacking a source link. An agent has enough to call it correctly and interpret 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 description coverage is 100%, so the schema already documents all four parameters including defaults, pagination semantics, and the no-cap rule. The description restates those same points (limit/offset/total_matched, min_amount USD floor, days window) without adding syntax or format detail beyond the schema, 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?

States a specific verb+resource+scope: 'recently signed U.S. federal new awards from USAspending.gov, newest first.' It also clarifies sort order and data source in the first clause, which is everything needed to distinguish it from the insider/13F/activist 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?

Gives clear operational context (default 25, page with offset, total_matched for full count) and notes the optional min_amount and days filters. It does not name a sibling alternative or an explicit when-not condition, but the sibling set is an entirely different domain, so the routing risk is low.

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 readOnly/idempotent/non-destructive, yet the description adds substantial new context: data is up to ~45 days stale (lag_days), ticker is always null, missing prior quarter is the explicit 'first_filing_on_record' state, coverage is per CIK not per brand, and the universe is re-ranked quarterly. These are non-obvious behavioral traits an agent cannot derive from 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?

Front-loads the core concept in the first sentence, and most sentences (staleness, null ticker, CIK coverage, universe caveat) earn their place. It is dense and long, but the caveats are genuinely load-bearing for correct interpretation rather than padding.

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?

Despite no output schema, the description enumerates the returned fields (as_of_quarter_end, filed_date, lag_days, value_usd, cusip, issuer_name, filing_url) and the pagination/limit model. An agent has everything needed to call and interpret it 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 100%, so the schema already documents every parameter. The description restates defaults (25 rows, offset paging, days window) but adds little syntax or semantics beyond total_matched, 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?

States a specific verb+resource ('what large institutional filers CHANGED quarter-over-quarter in their SEC 13F-HR holdings') and immediately frames the delta as the product with the raw snapshot as input. This distinguishes it from siblings like verify_13f_holding without the agent opening any 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?

Gives clear context for when this is appropriate: it covers only long US 13(f)-listed positions (no shorts/non-US/options), it reports filings not interpretation, and it is 'NOT a trading edge'. It stops short of explicitly naming an alternative sibling or stating when-not-to-use in favor of another tool.

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 establish the safe read-only/idempotent profile, but the description adds substantial domain behavior: the meaning of uniform_price_cluster, the caveat that Form-4 code P conflates open-market and offering/conversion purchases, the ranking rule (genuine clusters above uniform-price ones), and default ordering/pagination. This is exactly the kind of context annotations cannot carry.

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 and front-loads the core definition and the highest-value caveat before moving to paging details. It is longer than typical, but nearly every clause carries signal; only the parameter recap at the end is somewhat redundant with the schema.

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 takes on the burden of describing returns (newest 25 by default, total_matched full count, per-record filing_url) and does so. Combined with the flag semantics, an agent has everything needed to interpret results 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%, so all four parameters are already documented, and the description largely restates limit/offset/days/ticker and the total_matched count. It adds only marginal framing (newest-first default) beyond the schema, 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?

States a precise verb+resource with an exact inclusion rule ('Rule-2 cluster buys only, >=2 insiders buying the same issuer in-window') and characterizes it as the highest-signal subset. An agent can distinguish this from the broad insider_signals_* siblings without opening any 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 definition of what constitutes a cluster buy implies when it applies, and the warning about uniform-price clusters vs genuine conviction is useful selection guidance. However, no sibling is named and no explicit when-to-use/when-not-to-use routing is given (e.g. vs insider_signals_by_ticker or insider_filing_lookup).

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for adding beyond them: it discloses the signal-filter semantics ('only purchases that pass the signal filter are returned') and the error behavior when no gated filing matches.

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?

Three tight sentences, front-loaded with what is returned and followed by the filter caveat and error case. No filler, though the trailing 'with their filing_url' clause is slightly tacked-on.

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 sensibly conveys the return content (signal records plus filing_url) and the error path. For a single-parameter, fully-annotated read tool this is nearly complete; only pagination/record-count behavior is unaddressed, and it may be unnecessary.

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 single accession parameter already carries a format example, so the description adds no syntax or format detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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 a specific verb+resource: retrieves Rule-2 signal records for one SEC filing accession. This clearly separates it from siblings like insider_signals_by_ticker or verify_insider_purchase, though the 'Rule-2 signal' jargon is domain-specific and not explained.

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 by 'lookup by accession' and the mention of filing-level records, but the description never explicitly says when to pick this over insider_signals_by_ticker or the verify_* siblings, nor what prerequisite (having an accession) drives its selection.

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 readOnly/idempotent/non-destructive, so the bar is lower. The description adds real behavioral context beyond them: a default of 25 newest-first, offset paging, that total_matched reports the full count, and that each record carries its source filing_url. It does not mention rate limits or ordering edge cases, keeping it below a 5.

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 with the core scope front-loaded and paging details packed into a parenthetical. Every clause carries information, though the parenthetical is dense enough that a slightly cleaner split would read better.

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 read-only list tool with no output schema, the description covers scope, defaults, paging, the total-count field, and a per-record field, which is enough to call and interpret it correctly. It stops short of explaining what qualifies as a 'Rule-2' signal, leaving a small domain 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 coverage is 100%, so the schema already documents start/end/days/ticker/limit/offset semantics; the baseline is 3. The description largely restates the same limit/offset/total_matched behavior and adds the 'inclusive' range framing, so it contributes only marginal meaning beyond 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?

States a specific verb+resource+scope: 'Rule-2 insider-buy signals filed within an inclusive ISO date range.' The date-range framing cleanly separates it from insider_signals_by_ticker and insider_signals_today without the agent needing to open a 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 description implies when to use it (date-range browsing) and documents defaults/paging, but never explicitly names an alternative such as insider_signals_by_ticker or insider_signals_today or states the condition that picks one over the other. Usage is inferable from the sibling names rather than stated.

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 annotations declaring readOnlyHint, idempotentHint, and openWorldHint=false, the safety profile is covered. The description adds useful behavioral details: returns newest 25 by default, pagination behavior, total_matched count, and that only filtered purchases are included. It doesn't mention rate limits or auth, but for a read-only signal tool this is adequate.

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, front-loaded with the core purpose, then pagination and filtering caveats. Every clause earns its place; no repetition or 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?

Given no output schema, the description explains the return shape (newest 25, total_matched, filing_url per record) and filtering behavior. It omits whether authentication or specific permissions are needed, but for a read-only public-signal tool that 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%, so the schema already documents all four parameters thoroughly. The description reiterates limit, offset, and days but adds no new syntax or format details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 precise verb (returns), resource (Rule-2 insider-buy signals), and scope (one ticker, case-insensitive). It is clearly distinguishable from siblings like insider_signals_today or insider_signals_by_date_range, which lack the ticker-specific focus.

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 implies usage for a single ticker and mentions pagination via limit/offset, but does not explicitly state when to prefer this over insider_cluster_buys or insider_signals_by_date_range. The context is clear but alternatives are not named.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds real substance beyond them: the caveat that code P is not necessarily open-market and that offering_context=true means an allocation rather than a buy. It also discloses the default page size and the total_matched count, which is exactly the kind of data-quality/pagination context an agent needs.

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?

Front-loaded with the core identity (rule-2 code P purchases today) before moving to caveats and pagination. Dense but each clause carries information; slightly long for a single block of prose.

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 helpfully names key response fields (offering_context, total_matched, filing_url) and the pagination contract, so an agent can interpret results. It stops short of describing the full record shape, but nothing essential to correct invocation 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 days, limit, offset, and ticker are fully documented in the schema already; the description largely restates limit/offset behavior and the default of 25. Baseline 3 is appropriate because the schema carries the parameter meaning.

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 a specific verb+resource+scope: 'Rule-2 insider-buy signals filed today (SEC code P purchases)'. The 'filed today' scoping plus the code-P detail distinguishes it from insider_signals_by_date_range and insider_signals_by_ticker without opening either 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?

It explains how to call it (default 25, page with offset/limit, optional days/ticker filters) but never explicitly says when to prefer this over the sibling date-range or ticker variants, nor any when-not conditions. Usage is implied rather than stated.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial beyond-schema behavior: every response states the coverage window, values are quarter-end as-of and up to ~45 days stale, only long US 13(f) positions are covered, and not_held vs not_found are semantically distinguished.

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?

Front-loaded with the core check, followed by the four outcome states and then the Rule-2 constraints. Dense but every clause carries information; the status enumeration is slightly heavy but justified by the tool's ambiguity-prone semantics.

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?

No output schema exists, yet the description effectively documents the return contract by naming each status value, and it discloses coverage-window and staleness caveats. For a 6-parameter verification tool this is complete enough to call 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 100%, so the baseline is 3. The description reinforces the issuer_name/cusip vs filer matching rule and the 'ticker is never guessed' constraint, but this overlaps the schema's own parameter descriptions rather than adding new syntax or format guidance.

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 a specific verb (verify/check) and resource (a fund's 13F holding of an issuer as of a quarter) and explicitly distinguishes itself from sibling verify_* tools by tying to SEC Form 13F-HR. The distinct outcome semantics (held/not_held/not_found/out_of_coverage) make it 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 use case is clear: check whether a filer held an issuer in a given quarter, with explicit coverage-window routing via out_of_coverage and the not_held vs not_found distinction. It does not name sibling alternatives or state exclusions explicitly, so it falls short of a 5.

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 carry the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial non-obvious behavior: the full status taxonomy (confirmed/not_found/partial/out_of_scope/out_of_coverage), the itemised claimed-vs-filed diff on partial matches, the ±3 filing-day date tolerance, the always-disclosed coverage window, and the Rule-2 constraint that item codes are parsed from the filing rather than inferred from prose.

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?

Front-loaded with the core action and claim shape, then enumerates outcomes efficiently. The dense em-dash clauses make the status list slightly harder to scan than it needs to be, but there is little wasted 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?

No output schema exists, so the description must explain returns — and it does, enumerating each status and what accompanies it (source filing plus link on confirmed, itemised diff on partial). Combined with the coverage-window disclosure and scope exclusion, an agent has everything needed to call and interpret 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 description coverage is 100%, so all seven parameters are already documented in-schema, including the CIK format, ISO dates, accession format, and comma-separated item codes. The description references the cik/company/accession grouping but adds no syntax or format detail beyond the schema, 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?

States a specific verb (verify a claim) against a specific resource (SEC Form 8-K filing record), and names the exact claim shape it accepts (registrant + item codes + timeframe). This is clearly distinguishable from the sibling verify_* tools that target 13F/13D/insider purchases.

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?

Gives strong in-scope context and explicitly carves out out_of_scope claims (meaning/materiality of the filing body), which functions as a when-NOT-to-use statement. It doesn't name sibling tools or say when to prefer a related verification tool, so it stops short of a 5.

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 cover safety (readOnly, idempotent, non-destructive), and the description adds substantial context on top: the full status vocabulary (confirmed/not_found/partial/out_of_scope/out_of_coverage), the itemised claimed-vs-filed behavior for partial matches, and the explicit 'Rule-2: no estimates — absence is reported as absence' policy. That is meaningful disclosure beyond the 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?

Front-loads the purpose, then enumerates return statuses compactly, ending with the no-estimates rule. Dense but each clause carries information; the status list is long but necessary given no output schema exists.

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 compensates by enumerating every possible status and noting that the coverage window is always reported. For a 9-parameter verification tool this gives the agent everything needed to interpret results and call it 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 100%, so the schema already documents every parameter, including the ±3 filing-day and ±0.5pp tolerances. The description only restates the claim dimensions (ticker/subject, filer, percent, intent, timeframe) without adding matching semantics 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?

Starts with a specific verb+resource ('Check a claim about an activist stake ... against the filed Schedule 13D/13D-A record') and enumerates the claim dimensions it evaluates. It is clearly distinguishable from the sibling verifiers (verify_13f_holding, verify_8k_event, verify_insider_purchase) by naming the 13D/13D-A filing domain.

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?

Gives explicit scope boundaries: passive 13G returns out_of_scope and claims outside the collected window return out_of_coverage, with the coverage window always reported. It lacks explicit routing to sibling tools for out-of-scope cases, so it stops just short of full when/when-not/alternatives 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 cover the safety profile (readOnly, idempotent, non-destructive), but with no output schema the description carries the return-value burden and does so richly: it enumerates all five statuses, explains the 'partial' itemised claimed-vs-filed behaviour, states the coverage window is always reported, and declares Rule-2 (absence reported as absence, no estimates). That is behavioural context well beyond the 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?

Front-loaded with the core action, then the status vocabulary, then the coverage/Rule-2 guarantees. It is dense but every clause (statuses, coverage window, no-estimates rule) earns its place. Slightly heavy as one block of prose, keeping it from 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?

With 9 params at full schema coverage, no output schema, and closed-world annotations (openWorldHint=false), the description supplies exactly the missing piece: the return-status taxonomy and the coverage-window guarantee. Nothing an agent needs to invoke or interpret it correctly is absent.

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 schema already documents every parameter, including the ±3 filing-day date tolerance and the ±5%/±$1 amount tolerance. The description only restates the claim fields (ticker/issuer, person, amount, timeframe) without adding syntax or matching semantics beyond the schema, so 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?

States a specific verb+resource: 'Check a claim about an insider open-market buy ... against the filed record.' The parenthetical enumerates the claim dimensions (ticker/issuer, person, amount, timeframe), and the opening clause immediately distinguishes this verification tool from the signal/aggregation siblings (insider_signals_*, insider_cluster_buys).

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 scopes usage by stating only open-market buys are covered and that sales/options/grants return out_of_scope, which tells the agent when this tool is the wrong choice. It stops short of naming a specific alternative sibling (e.g. insider_filing_lookup) for the out-of-scope cases, so it is clear context without full alternative routing.

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