TradeStar Insider

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the sort order (newest first, then stated-intent strength), the per-row payload (filing_url and a 600-char item4_excerpt quoted as data), and two real behavioral caveats (13G excluded, filings lacking a source link 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?

Front-loaded with the 'Use when' trigger, then scope, then return shape, then caveats in a logical order with zero filler. It is dense but every clause carries information, with only slight length pressure from the item4_excerpt parenthetical.

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 must describe return values and it does: sort order, per-row fields, excerpt cap, and drop/coverage rules. Combined with 100% schema coverage and safety annotations, an agent has everything needed to call and interpret this 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 all five parameters including pagination and limit semantics. The description only names three filters (ticker, min_percent, days) that 'narrow' results, adding no syntax or edge-case detail beyond the schema. 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 (returns) and resource (activist Schedule 13D/13D-A filings on US-listed companies), and pins the domain precisely enough to be distinguished from the passive-13G world it explicitly excludes. An agent can tell what this returns 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?

Opens with an explicit trigger ('Use when the user asks about activist investors, hedge-fund stakes, or recent 13D filings') and gives an exclusion (passive 13G is not covered). It does not name the sibling verify_activist_13d as the alternative for verification, so routing to the closest sibling is left 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is covered. The description adds real behavioral value beyond them: ordering (newest first), the amount/days filtering semantics, that each award carries its source award_url, and a non-obvious data-loss caveat that awards without a source link are silently 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?

Three tight sentences, front-loaded with the trigger condition, then return shape, then the caveat. No filler, and the most surprising information (dropped awards) is placed last for emphasis.

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 trigger, ordering, filter semantics, and the key gotcha about dropped awards. Pagination and total_matched are only in the schema, which is acceptable since the schema 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 all four parameters (days, limit, offset, min_amount) are already documented in the schema. The description only restates min_amount and days, adding no format or syntax detail beyond it — the baseline 3 applies 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 ('Returns newly signed federal awards') and explicitly frames the trigger scenario ('recent federal contracts, government awards, or who won a U.S. federal contract'). The domain is clearly distinct from the SEC/13F/insider siblings, so an agent can route 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?

Opens with an explicit 'Use when the user asks about...' condition, giving clear positive selection guidance. It does not name alternatives or state when NOT to use it, but the sibling set is an unrelated 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 establish read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: newest-first ordering, that ticker is deliberately left null rather than guessed, and a caveat that the delta is not a trading edge, plus a pointer to a per-response coverage note.

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 dense sentences, front-loaded with the trigger, then filters, then row shape, then caveat. The row-field enumeration is long but justified because there is no output schema; nothing is pure 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 usefully compensates by listing the returned row fields (as_of_quarter_end, filed_date, lag_days, value_usd, cusip, issuer_name, filing_url) and flagging the null ticker. It also scopes the data universe via the coverage note. Only the CIK/universe scope is deferred rather than stated, which 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 six parameters in detail (including the limit<=0 no-cap rule and offset paging). The description only names four of them as filters and adds the 'newest first' ordering, which is not in the schema but is minor. Baseline 3 is correct here.

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 (quarter-over-quarter SEC 13F position deltas) and enumerates the exact user phrasings that should trigger it ('what a fund bought or sold', 'opened/added/trimmed/exited a position'). This is precise enough to separate it from the verify_* siblings, which check a specific claim rather than surface deltas.

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 clear positive trigger conditions with concrete example questions, so an agent knows when to reach for it. It stops short of naming an alternative or an exclusion (e.g., when to prefer verify_13f_change), so it is context without 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 establish readOnly/idempotent/non-destructive, and the description adds substantive traits beyond them: ordering (newest-filed first), per-row return contents, and a real behavioral caveat that uncollected originals still appear with original_in_corpus=false and null before/after values that are 'never guessed'. That linkage-by-issuer/owner/period detail is exactly the kind of edge-case behavior 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?

The trigger sentence is front-loaded and the return-shape and caveat follow logically, with no redundant filler. It is dense and slightly cluttered with field lists in prose, which keeps 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 no output schema, the description shoulders the burden of describing the return shape (amendment_accession, filed_date, issuer/insider, filing_url, original_accession, changed_fields) and the not-collected edge case. For a nine-parameter read tool, 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 the schema already documents all nine parameters with formats and defaults. The description only summarizes that ticker, issuer_name, person, start/end and days 'narrow' the results, adding no syntax or filtering semantics beyond the structured fields; baseline 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 uses a specific verb and resource ('Returns 4/A amendments, newest-filed first') and scopes the task to amended/corrected/restated insider filings, which cleanly separates it from siblings like insider_buys and insider_cluster_buys. An agent can identify the tool 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?

It gives an explicit trigger ('Use when the user asks which insider filings were amended, corrected, or restated'), which is strong when-to-use guidance. It does not name an explicit alternative sibling or a when-not condition, 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 the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantive context: the signal filter restricts results, code P is not proof of a buy, and rows carry `partial_fields` explaining nulls. It does not cover rate limits or response envelope details, but the added caveats are real behavioral disclosure.

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 usage trigger, then parameter routing, then the row shape, then the caveat — each sentence carries distinct information with no restatement of the schema or name.

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 enumerating row fields (filing_url, offering_context, transaction_date, aff10b5One, is_amendment/original_accession, partial_fields) is necessary and done. All 8 parameters are documented in the schema, and the one semantic trap (code P vs. a genuine buy) is called out.

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 genuine value the schema does not: how the filters combine ('ticker, start+end for an inclusive ISO range, or neither for today's buys') and what the default path yields (SEC code P for today). It also explains the role of `days` and `include_unlisted` in prose.

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 (insider buys / SEC Form 4) and immediately scopes it by ticker, today, or date range, which separates it from siblings like insider_cluster_buys, insider_amendments_recent, and verify_insider_purchase. An agent can route to it 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 opening sentence gives explicit trigger conditions ('Use when the user asks which insiders bought a stock...'), and the second sentence tells the agent exactly how to shape the call (ticker, start+end, or neither for today). It stops short of naming sibling alternatives or exclusion cases, so it is clear context without full when-not 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 cover the safety profile (read-only, idempotent, non-destructive), so the bar is lower, yet the description still adds real behavioral context: results are restricted to signal-filtered purchases, rows arrive newest first, and specific fields (partial_fields, is_amendment/original_accession, uniform_price_cluster) reveal data quality and lineage 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?

Front-loaded with the usage condition and the cluster definition, then a compact enumeration of row fields. It is dense but every clause carries information; the field list is somewhat list-heavy but justified since there is no output 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 must describe returns, and it does so field by field, plus discloses the filtering caveat and the null-handling contract via partial_fields. Nothing material an agent needs to invoke or interpret this tool 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 all six parameters are already documented with their own semantics; the description only restates that days and ticker narrow the result set. Baseline 3 applies when the schema does the heavy lifting and the description adds no format or edge-case detail beyond it.

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 (returns insider cluster buys) and pins down the scope precisely: two or more insiders buying one issuer in the window. This clearly separates it from the sibling insider_buys, which would cover single-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?

"Use when the user asks about cluster buying or several insiders buying the same company" gives an explicit trigger condition, and the caveat that code P alone is not proof of a buy tells the agent when a result should not be over-read. It stops short of naming sibling alternatives like insider_buys to route away from this 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?

Goes well beyond the readOnly/idempotent annotations by enumerating the four result statuses and, critically, warning that not_found does NOT mean the fund didn't hold the position and that filing-verified deltas cannot confirm an unchanged holding. That is exactly the negative-result context an agent needs to avoid over-claiming.

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 trigger sentence and then the return semantics; the parentheticals are dense but each carries real information. Slightly long, but no sentence is 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 supplies the return-value vocabulary and the interpretive caveats that would otherwise be missing, including the out_of_coverage state and the delta-only limitation. An agent has everything needed to call it 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%, so filer/issuer_name/cusip/quarter semantics are already documented in the schema. The description restates the fund + issuer + quarter composite query shape but adds no new format or constraint detail, 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?

Names a specific verb (verify/fact-check) plus the exact resource (a 13F position-change claim by a fund in an issuer in a quarter), which cleanly separates it from siblings like verify_activist_13d, verify_8k_event, and verify_insider_purchase.

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?

Opens with an explicit 'Use when...' trigger naming the user intent, filer and issuer inputs. It also states a when-not via the caveat that unchanged holdings cannot be confirmed, though it does not explicitly name which sibling to use instead when the claim is about 13D/8-K/insider activity.

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 goes well beyond them by enumerating the five possible outcomes (confirmed/not_found/partial/out_of_scope/out_of_coverage) and disclosing the filing-verified caveat that item codes come from SEC controlled vocabulary and are never inferred.

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 that front-load the trigger and then the return modes, with no filler. The enumeration of statuses is information-dense but earns its place since 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?

For a seven-parameter, zero-required verification tool with no output schema, the description supplies exactly what is missing elsewhere: the matching semantics, the full set of return modes, and the scope caveat, leaving no material gap for an agent calling 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 all seven parameters are already documented in the schema. The description restates the parameter groups ('registrant (cik/company/accession), item code(s) and dates') without adding syntax or format detail beyond what the schema provides, 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 and resource ('verify or fact-check that a company filed an 8-K carrying specific SEC item code(s)') and scopes it to the SEC Form 8-K domain, clearly distinguishing it from the sibling verify_13f_change, verify_activist_13d and verify_insider_purchase 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 leading 'Use when...' clause gives a clear trigger condition, and the out_of_scope status explicitly tells the agent what this tool will not cover (claims about a filing's meaning). No sibling alternatives are named, so it falls short of a full when/when-not/alternatives treatment.

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?

Well beyond the annotations (readOnly/idempotent/openWorld=false, which only confirm a safe read), the description discloses the full outcome taxonomy (confirmed, not_found, partial, out_of_scope, out_of_coverage), that every response states the coverage window checked, and the critical caveat that absence is reported as absence, never guessed. That is exactly the operational honesty an agent needs for a fact-checking tool.

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 usage trigger, then outcome taxonomy, coverage statement, and caveat in tight sentences. The return-value enumeration is denser than strictly needed, but every clause carries signal and nothing is redundant 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 must explain returns — and it does, listing every status and the coverage-window disclosure. Combined with a fully documented 9-parameter schema and safety annotations, an agent has everything needed to call this 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 the schema already carries the tolerance semantics (±3 filing days, ±0.5 percentage points, the intent enum, case-insensitive ticker). The description only loosely echoes the claim components, adding no syntax or format detail 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?

States a specific verb (verify/fact-check) plus resource (activist 13D claim against SEC Schedule 13D/13D-A), and the enumerated claim facets (ticker/subject, filer, percent-of-class, intent, timeframe) pin down exactly what is being checked. An agent can distinguish it from verify_13f_change, verify_8k_event, and verify_insider_purchase 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?

Opens with an explicit when-to-use trigger ('verify or fact-check a claim about an activist stake or 13D filing') and gives an exclusion: passive 13G returns out_of_scope. It does not name the sibling verifier tools (e.g. verify_13f_change) as alternatives, so routing is implied rather than spelled out.

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, non-destructive and closed-world, and the description adds genuine behavior beyond that: the full status vocabulary (confirmed/not_found/partial/out_of_scope/out_of_coverage), the per-filing fields returned, and the key epistemic caveat that absence is reported rather than guessed.

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, with the trigger condition correctly front-loaded before the return-value detail. Slightly packed with status/field enumerations, but nothing is redundant or wasteful.

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 fully carries the burden of explaining return statuses and per-filing fields, and it does so alongside the coverage caveat. An agent can call this correctly and interpret the response without further 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 description coverage is 100%, so every parameter, including the ±3 filing-day and ±5%/±$1 matching tolerances and the accession-alone override, is already documented in the schema. The description restates the claim-vs-accession split and the P-code-only scope but adds little syntax or meaning not already present.

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/fact-check) and resource (an insider-buying claim against SEC Form 4), plus a second mode (pull purchases by accession). It is clearly distinguishable from siblings like insider_buys and insider_cluster_buys, which list rather than adjudicate claims.

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?

Opens with an explicit trigger ('Use when the user wants to verify a claim...') and describes the alternate accession-only path. It doesn't explicitly name which sibling to reach for when the user merely wants a list of buys (insider_buys), so routing against alternatives is implied rather than spelled out.

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