SEC EDGAR Insider Trades & Financials

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral detail that annotations do not: results come newest-first and are de-duplicated by period. It does not mention pagination, missing-concept errors, or how many data points a company typically reports.

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 behavior (time series, source, ordering, dedup), then examples, then period guidance. The long inline list of example tags is dense but earns its place by reducing concept-name guessing; a few could be trimmed.

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 conveys ordering and de-duplication, which is most of what an agent needs to interpret the series. It stops short of describing the returned fields (period end, filed date, form, value/frame) and what happens when a concept is not reported, which is a modest 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 baseline is 3; the description still adds meaning by mapping period=annual to 10-K fiscal years and quarterly to 3-month windows, and by naming which taxonomies appear in practice (us-gaap, dei). The unit and limit parameters are left entirely to 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 (time series of a single XBRL concept per company) and names the backing source (SEC companyconcept data). The ordering and de-duplication scope are part of the stated purpose, and no sibling tool does this, so it is easy to route to.

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 concrete concept tag examples across us-gaap and dei, and explains when to pick period="annual" (fiscal years / 10-K) versus "quarterly" (3-month periods). It never states when to prefer a sibling such as get_company_snapshot or get_company_filings instead, so alternative routing is left implicit.

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/open-world, so the safety profile is covered. The description adds real value beyond that: newest-first ordering, the concrete return fields (filing date, report period, description, document URL), and that 8-K item numbers are included.

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 compact sentences; the resource and coverage come first, filtering second. The long form-type list is dense but earns its place by telling the agent what a single call can retrieve.

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 names the returned fields and sort order, and cap/pagination is handled by the documented limit parameter. Only the relationship to search_filings is left unexplained for a 5-param, open-world 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?

Schema coverage is 100%, so ticker_or_cik, forms, limit, since and until are all documented in the schema itself. The description only echoes the forms and date-range filters and adds no format or boundary detail beyond what structured fields already say. 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 and resource ('Latest SEC filings for a company') and enumerates the form types covered plus the fields returned, so an agent knows exactly what it gets. It does not, however, distinguish itself from the sibling search_filings, which is the most likely source of confusion.

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?

'Filter by form types and a date range' implies the intended use but never states when to choose this over search_filings or get_insider_trades. No exclusions, prerequisites, or alternative-routing guidance are given.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds meaningful substance beyond that: each metric carries latest annual, prior annual, YoY %, latest reported period, plus derived margins and debt-to-equity, all in USD 'as reported' — details an agent would otherwise have to discover by calling.

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, front-loaded with the source and scope before the metric inventory. The metric list is long but every item earns its place by telling the agent whether a needed figure is retrievable without a follow-up call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining returns and does so thoroughly — metrics, comparison periods, derived ratios, currency. The only missing piece is failure behavior for unresolvable tickers/CIKs and whether all metrics are always present.

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%, with ticker_or_cik documented including examples for both ticker and CIK forms. The description says nothing additional about the parameter (e.g. whether an ambiguous ticker fails or resolves), so it matches the baseline where the schema does the work.

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 (10-K/10-Q XBRL financials) and enumerates exactly which metrics are returned, so the agent knows what it gets. It doesn't differentiate itself from the sibling get_company_concept, which also returns XBRL financial data, leaving the agent to infer that this is a bundled summary rather than a single-concept timeseries.

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 explicit when-to-use or when-not-to-use guidance and no sibling is named, but the word 'snapshot' plus the 'latest annual value, prior annual value, YoY growth' framing implies a one-shot summary in contrast to a per-concept time series. That implication is the only routing signal available.

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/openWorld, so the bar is lower, yet the description still adds real value: it discloses the cost model ('each filing costs one SEC request') tied to the filings parameter, and it explains the return payload shape (summary object plus one row per transaction). It does not mention failure modes such as unknown tickers or CIKs with no Form 4s.

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 scope, then returns, then a usage hint — a sensible ordering with no filler sentences. The long comma-separated field enumeration is dense but every field listed is useful given 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 carries the burden of describing return values, and it does so thoroughly (summary aggregate fields plus per-transaction fields including the 10b5-1 flag and filing link). Combined with a 100%-covered schema and clear read-only annotations, an agent has everything needed to 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 coverage is 100%, so the baseline is 3. The description does add meaning for the codes parameter by expanding the transaction code legend (P/S/A/M/F/G), which goes slightly beyond the schema's bare examples, but that same legend is largely restated ground already implied by the enum and per-parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: 'Recent SEC Form 4 insider transactions for one company (ticker or issuer CIK) or one insider (reporting-owner CIK)'. An agent immediately understands both input modes and the output shape. It does not name or contrast with the sibling get_market_insider_buys, so it stops short of full sibling differentiation.

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?

Only guidance is 'Use side="buy" to see only open-market purchases', which is a parameter-level filter hint rather than when-to-use-this-tool guidance. There is no statement of when to prefer this over get_company_filings or get_market_insider_buys, and no prerequisities 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower; the description nonetheless adds real behavior — the ranking order is disclosed, and crucially the data-origin caveat (rolling EDGAR Form 4 scan, coverage starts at deployment, capped at 30 days) tells the agent results are incomplete for older windows. It does not describe the shape of each issuer group, which matters since there is no output 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?

Four sentences, front-loaded with what the tool returns before the definitional aside and the coverage caveat. Every sentence earns its place — the cluster-buy definition and the EDGAR coverage limit are non-obvious and load-bearing.

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 five-parameter read-only screening tool with full schema coverage and no output schema, the description covers scope, ordering, filter intent and data-freshness limits. The remaining gap is that it never sketches the per-issuer result structure, which the agent must guess given the absent output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with defaults, bounds and a helpfully worded enum for role, so the schema already carries the parameter burden. The description mainly restates the filter set ('look-back days, minimum total value, minimum insiders and role') and adds only marginal meaning beyond that, plus the cluster-buy hint that is already in the min_insiders schema description.

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 — recent open-market insider purchases (Form 4 code P) — plus the scope (all U.S. public companies) and ordering logic (grouped by issuer, ranked by insider count then dollar value). The market-wide framing implicitly separates it from the company-scoped sibling get_insider_trades, 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?

Gives clear operating context: it's a screening tool with look-back window, value, insider-count and role filters, and explicitly defines the 'cluster buy' use case with the min_insiders=2 trigger. It stops short of naming the sibling (get_insider_trades) as the alternative for single-company lookups, so the when-not guidance 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, open-world behavior, so the safety profile is covered. The description adds the useful behavioral fact that resolution is bidirectional, but it does not say how a bare string is disambiguated between ticker and CIK, nor what happens on an unknown symbol (error vs empty result).

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 short sentences with zero filler; the conversion semantics come first and the downstream-use hint second. Nothing is repeated from the name or title unnecessarily.

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 correctly names the return values (CIK, ticker, company name) and the reason to call it. It is complete for a one-parameter lookup, with only the not-found/ambiguity behavior left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter already documents both accepted forms with examples. The description restates the either/or input nature but adds no format, casing, or normalization guidance 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 (convert/resolve) and resource (ticker ↔ SEC CIK + company name), including both directions of the mapping. An agent can immediately tell this is a lookup/identifier-resolution tool and distinguish it from the filing, concept, and snapshot 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?

Explicitly says to use it to obtain the CIK needed by search_filings, which chains it to a concrete downstream tool. It stops short of stating when NOT to use it (e.g., that it returns no filing or price data, which is what the other siblings cover).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the returned fields (company, form, filing date, 8-K items, document URL), the 2001 corpus boundary, and the default 365-day date window that silently narrows results — a real gotcha an agent would otherwise miss.

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?

Four short sentences, front-loaded with what the tool is before syntax, return shape and defaults. Every sentence carries non-redundant information and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter search tool with full schema coverage, no output schema and comprehensive annotations, the description covers purpose, syntax, returns and defaults. The only remaining gap is paging behavior against EDGAR's 100-result pages, which is only referenced in the offset parameter rather than the description.

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 with types, patterns, defaults and bounds; the baseline is 3. The description does add one thing the schema lacks — boolean OR support — but otherwise restates form-type, date-range and CIK filtering that the schema already spells out in more detail.

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 ('Full-text search across SEC filings') plus a coverage window ('since 2001') and the underlying system (EDGAR FTS). An agent can immediately separate this from structured siblings like get_company_filings or get_company_concept, since this one searches text across all filers rather than returning one company's structured records.

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 the query-syntax and filter guidance, and the default 365-day window hints at typical use, but there is no explicit when-to-use statement or routing to alternatives such as get_company_filings once a CIK is known. The ciks param points at resolve_company, which is helpful, but the choice between this tool and get_company_filings 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.