Stockfacts

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

Annotations already declare readOnly, idempotent, openWorld=false, so the safety profile is covered. The description goes further by disclosing what the response contains (last successful updates, update schedule, server usage limits), which is genuine behavioral context an agent needs, though it says nothing about response size or rate limits on the call itself.

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?

One dense enumeration sentence followed by a short usage imperative — front-loaded and functional, though the field list is long and could be trimmed since an output schema exists. No filler or repetition.

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 parameterless read-only inventory tool with an output schema, the description fully covers scope (which datasets), freshness semantics (ISO 8601 UTC update timestamps), and the decision it supports. Nothing needed to invoke 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?

Zero parameters, so there is no parameter semantics to miss; baseline 4 applies. The description correctly signals this is a no-argument inventory call.

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 concrete verb+resource: returns the server's data coverage and freshness, enumerated by dataset (Form 4, 13F quarters, 13D/13G/144, congress trades). This is clearly distinct from the sibling fetch tools like get_insider_trades or get_stock_13f_holders, which return records rather than coverage metadata.

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 closing sentence is an explicit call-to-action: 'Call it to check whether a date or quarter is covered.' This gives clear when-to-use context (validate coverage before querying), but names no alternative tool or when-not-to-use condition, so it stops short of the top band.

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 read-only/idempotent safety, but the description adds substantial behavior: value_outlier suppression and flagging logic, which notices are excluded (superseded by Form 144/A), the 200-row pagination cap, and the XML coverage start date. This is far beyond what annotations provide.

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?

Dense but front-loaded: purpose first, then exclusion rules, then flagging rationale, then filter behavior, then row shape and limits. It is long, but nearly every clause carries operational information; only the intermediate flagging-mechanism detail 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?

Given an output schema exists, the description needn't enumerate return values, yet it does helpfully list row fields, plus pagination, coverage caveats, and filtering edge cases. Nothing an agent needs to call this 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 coverage is 100%, so the baseline is 3, but the description meaningfully augments it – 'whole history' semantics for ticker/seller_cik, the query matching seller or company name, and the market-wide 365-day/default-30-day behavior tied to date params. These add semantics the schema does not.

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 (Form 144 notices of proposed sales of restricted/control stock by insiders) with a clear scope and ordering ('newest first'). It also distinguishes the concept semantically from completed trades ('a notice is a plan to sell, not a completed sale') which separates it from siblings like get_insider_trades.

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 describes when to use ticker vs seller_cik vs query vs bare date filtering, and what happens in each case (whole history vs market-wide, 365-day cap, default 30 days). It also routes to get_data_coverage for the loaded range, naming an alternative for coverage questions.

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), but the description adds substantial behavioral context: non-derivative transactions only, exclusion of outlier rows, duplicate filings and issuers without tickers, SEC filing-time windows, USD amounts, and a 200-row cap. This is well beyond what the structured annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded: it opens with the overall purpose, then defines each list, then covers exclusions, shared fields, currency, and row limits. Every sentence carries specific information, and none appears to be 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 read-only screen-listing tool with a full output schema and strong annotations, the description provides everything needed: list semantics, filtering rules, data currency, row limit, and field compatibility with get_insider_trades. Return-value details are appropriately left to the 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%, so the schema already documents both parameters, making the baseline 3. The description meaningfully adds to the `list` parameter by defining each enum value's exact criteria and ranking, though it adds little beyond the schema for `limit` aside from restating the 200-row maximum.

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

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

The description names a specific resource (insider trading screens) and enumerates all six ready-made lists with their ranking criteria. It also distinguishes itself from the sibling get_insider_trades by stating that trade rows share the same fields, so an agent can tell it apart 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?

The description clearly explains what each screen represents and when those lists are useful, e.g., cluster-buys means 3+ insiders bought in 30 days. However, it does not explicitly state when to prefer this tool over get_insider_trades or other siblings, nor does it name exclusions or alternatives.

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

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

Annotations already declare a safe, idempotent read, so the bar is lower, yet the description adds substantial behavioral context: daily updates, 200-row cap with pagination via page, price_outlier rows excluded from rankings/totals, carried_from semantics for Form 4/A amendments, and rule_10b5_1 null before 2023. These are non-obvious traits an agent could not infer from the 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?

Front-loaded with the core purpose and a dense but largely waste-free paragraph; nearly every sentence carries field semantics or a constraint. It would be more scannable with structure, and the back-half semantics (carried_from, price_outlier) could be tightened, but there is little 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 an output schema present, the description need not explain return shapes, yet it still covers row granularity, aggregation rules, date formats, null conditions, and pagination limits. For a 10-parameter tool with zero required params, this is fully sufficient 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 description coverage is 100%, so a baseline of 3 applies, but the description goes further by enumerating the meaning of each transaction code (P, S, A, D, F, G, M, X, C, W, J) and restating the default codes P and S, which the schema only lists as values. It also clarifies that 'without ticker or insider_cik' triggers a 30-day market-wide limit, adding conditional meaning to those params.

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 ('Insider transactions from SEC Form 4 filings') and immediately scopes it with coverage start and update cadence. It is easily separable from siblings like get_insider_lists and get_superinvestor_activity, which cover different data.

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 usage context: 'Filter by ticker, insider_cik, filing-date range, codes, the primary insider's role and minimum value,' and explains that omitting ticker/insider_cik yields a market-wide query capped at 30 days, defaulting to the last 7. However, it never names or routes to an alternative sibling tool, so it falls short of explicit when-to-use-vs-alternative 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 read-only/idempotent/non-destructive, and the description adds substantial non-obvious behavior: split handling with split_factor and CUSIP changes, the 0.5% unchanged threshold, a 200-holding cap requiring pagination, exclusion of options from portfolio value, null url for tickerless securities, and suppression of changes when the prior quarter was not filed.

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 core purpose and defaults are front-loaded, and every clause carries real information rather than repetition. It is dense to the point of reading as one long block, which slightly hurts scannability, but there is no filler to cut.

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

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

For a tool this complex, the description covers the edge cases an agent must know before calling: pagination limits, split adjustments, missing-prior-quarter behavior, and option/sold-out reporting. Return fields are also covered by the output schema, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning about how parameters interact: the quarter parameter's default (latest filed) is tied to the change/sold-out logic, and the page hint is linked to the 200-holding cap. This slightly exceeds what the schema alone conveys.

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: retrieving one 13F filer (institution or curated superinvestor) by SEC CIK, plus its filing quarters and holdings. The scope is narrow and unambiguous enough that an agent can distinguish it from siblings like get_stock_13f_holders (the inverse direction) 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 description never says when to use this tool versus get_stock_13f_holders, get_superinvestor_activity, or search; the only routing hint ('Get it from search') lives in the schema, not the description. Usage is inferable from the resource name alone, but no explicit conditions or exclusions 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial non-obvious behavior: group filings report the largest single stake rather than a sum, share classes are split by CUSIP, legacy SC 13D/13G filings lack percent and are excluded, and holders stop filing after acquisition/delisting. This is exactly the kind of caveat an agent cannot infer 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?

Purpose and the field inventory are front-loaded, and every clause carries real information (field semantics, filing-form caveats, limits). It is dense and close to a wall of text, which slightly hurts scannability, but little is expendable.

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?

Though an output schema exists (so return values need not be explained), the description goes further by documenting field semantics and legacy/group-filing edge cases, leaving an agent fully equipped to interpret results and avoid misreading the figures.

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 both parameters (ticker, limit) are already documented in the schema and the description adds no further parameter detail. 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 resource (current holders of 5%+ of a stock via Schedule 13D/13G filings), ordering (largest first), and anchors it to a known reference (the Major holders tab on livermore.club). An agent can distinguish it from get_stock_13f_holders or get_ownership_filings, which cover different filing regimes.

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 context is implied through the described data scope and the pointed 'Call get_data_coverage for the loaded date range' note, but it never explicitly says when to prefer this over sibling tools like get_ownership_filings or get_stock_13f_holders. No when-not or alternative-selection guidance is 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 cover read-only/idempotent safety, and the description goes further: the 200-row cap and paging requirement, the note signal when the date range is narrowed, and the legacy/structured data split (percent/shares only available post-2023-12-18, legacy rows carry filer/company/date only). That is exactly the operational 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 purpose, then filters, then defaults, then row shape and data caveats — a logical progression. It is long and repeats the form definitions already in the schema, but nearly every clause carries information useful for calling the tool.

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 an 8-param, zero-required, read-only search tool with pagination and heterogeneous data vintages, the description covers filtering modes, defaults, pagination limits, and data-quality caveats. With an output schema present, the row-field enumeration is a bonus rather than a 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 baseline is 3, but the description adds real meaning beyond the schema: filer_cik includes filings where the entity is merely *named* as a reporting person, ticker returns the stock's whole history, and query can match a ticker as well as a name. The restated 13D/13G definitions duplicate the schema wording.

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 (Schedule 13D/13G filings by >5% holders), scope (newest first, market-wide vs. single-entity), and anchors to a concrete analog (livermore.club/en/ownership). It is clearly separable from siblings like get_stock_13f_holders or get_superinvestor_activity.

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?

Explains when the query is market-wide and how it is then capped to 365 days (default 30), and routes the agent to get_data_coverage for the loaded range. However, it never explicitly says when to prefer this tool over get_major_holders or get_stock_13f_holders.

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 read-only/idempotent safety; the description adds data provenance, daily refresh, statutory amount ranges, treatment of amendments/duplicates, and paper/scanned reports not being read. These are substantive behavioral constraints beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense block with semicolon-delimited clauses, front-loading identity and fields but running very long. Most content is relevant for this complex tool, though some output detail is redundant with the 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 an output schema present, the description need not explain returns, yet it goes beyond by covering data sources, refresh cadence, asset defaults, amount interpretation, and report limitations. Combined with annotations and 100% schema coverage, an agent has everything needed 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%, with both parameters fully documented including the asset enum. The description restates the default and asset meanings but adds no parameter-level syntax or meaning beyond what the schema already provides.

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

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

The description names the resource and scope precisely—one U.S. Congress member, by bioguide ID or name—and enumerates profile fields and trade statistics. It explicitly distinguishes this from get_politician_trades, so an agent can select it without inspecting 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?

It states the alternative tool and the selector: use get_politician_trades with the bioguide ID for trades. It also defines asset parameter choices and default, giving context for when to fetch other asset classes. The alternative routing is explicit.

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 substantial behavioral context: daily updates, 2020-01-01 coverage floor, exclusion of amended and duplicate trades, unreadable paper filings, null semantics for delay_days and amount_max_usd, and the 200-row-per-call cap with paging. This is far beyond what the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and much of the content earns its place (asset filtering rules, amendment exclusions), but it is a single dense paragraph that also enumerates output fields. Because an output schema exists, that field-by-field return listing is largely redundant and inflates the length.

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 the tool's complexity (13 params, multi-source disclosure data), the description covers data provenance, coverage dates, update cadence, deduplication/amendment handling, amount-range caveats, pagination, and default asset scope. An agent has everything needed to call it correctly; return-value detail is further backed by the 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 description coverage is 100%, so every parameter is already documented; the description mostly restates the same filters (asset classes, type values, date ranges). It adds minor value by clarifying that totals span all matching trades and that ticker matching behaves differently for non-listed tickers, but the baseline of 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 and resource ('Trades... reported by politicians') with precise scope: U.S. Congress House and Senate, one row per trade. It distinguishes this from corporate-insider data by explicitly naming the data source (PTRs from the House Clerk and Senate eFD), letting an agent tell it apart from get_insider_trades 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 context: default returns only listed securities, and it routes the agent to asset=other or asset=all for bonds, crypto, private holdings, etc. It also notes paper/scanned reports have no readable trades. It doesn't explicitly name a sibling alternative (e.g., get_insider_trades vs this), so routing is inferred 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 declare readOnly/idempotent/non-destructive, and the description goes well beyond by disclosing data-freshness semantics (a quarter is complete only after the 45-day filing deadline; in_progress_quarter is still being filed), delisting behavior (active=false, delisted_on Form 25 date, last full 13F quarter), and why share classes are separate tickers. This is exactly the kind of state caveat an agent cannot infer from 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?

Purpose and the alternative-tool routing are front-loaded, and every clause carries substantive information rather than filler. The main cost is readability: the opening sentence is a single long chain of parentheticals, which makes scanning harder than it needs to be, but the density is largely justified by the tool's complexity.

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 an output schema present the description need not explain return shapes, and it correctly spends its budget on the things structured fields cannot carry: quarterly completeness/timing, in-progress vs complete quarters, delisting edge cases, and share-class handling. An agent has everything needed to call this correctly and interpret freshness.

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 singular ticker parameter is fully documented in the schema, so the baseline is 3. The description adds real meaning beyond that by explaining that share classes (GOOG/GOOGL, BRK.A/BRK.B) are distinct tickers because 13F files each class separately, and by describing what happens when the ticker is delisted — useful semantics for interpreting the single input.

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?

Opens with a specific verb+resource ("Overview of one US-listed stock") and then enumerates the exact content blocks returned: SEC company facts, Form 4 P/S insider activity, 13F institutional ownership, and curated superinvestors. It explicitly names siblings (get_insider_trades, get_stock_13f_holders) as the source for the full lists, so an agent can separate this summary tool from them 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?

States when to route elsewhere: use get_insider_trades and get_stock_13f_holders for the full lists, implying this tool returns only aggregates. It also implicitly frames itself as a single-ticker overview. It does not, however, address other plausible alternatives such as get_institution or get_data_coverage, so the exclusions are incomplete.

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 read-only/idempotent/non-destructive, and the description adds substantial behavior beyond them: split-adjusted prior-share comparison with a 0.5% unchanged threshold, sold_out vs not_filed trailing rows, nulled change fields when changes_available is false, and totals that cover all holders rather than the page.

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, but the single dense paragraph dedicates much of its length to enumerating row fields and change semantics that the output schema already covers. The genuinely non-obvious domain logic (splits, sold_out/not_filed) earns its place; the field-by-field recap does not.

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 a complex financial domain, full annotation coverage, and an output schema, the description supplies exactly the logic an agent cannot infer: quarter completeness, filing lag, split normalization, and how non-holder rows are ordered. Nothing needed to interpret a call 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 parameters (page, limit, sort, ticker, quarter) are already documented in the schema itself. The description reinforces the quarter default and the 200-row page cap but adds little semantic detail beyond what the schema already carries.

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

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

The description names a specific resource (institutions reporting holdings in 13F-HR filings) and a specific scope (one calendar quarter, long US-listed positions), with defaults spelled out. It is clearly distinguishable from siblings like get_insider_trades, get_institution, and get_superinvestor_activity.

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 states the default quarter, the fallback for delisted tickers, and the 45-day filing lag, which tells the agent when results are meaningful. It never explicitly routes to a sibling (e.g., 'for a specific institution use get_institution'), so it stops short of full when/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?

Goes well beyond the annotations, which only cover the read-only/idempotent safety profile. It discloses subtle methodological rules: only superinvestors filing both quarters are compared, added/reduced is decided by share count not value, split adjustments via split_factor, ticker/CUSIP merging, and the 45-day 13F filing lag. This is exactly the kind of non-obvious 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?

Dense but front-loaded, leading with the core purpose before detailing edge cases. The long run-on sentences pack a lot of caveats, but each sentence carries substantive information rather than 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 an output schema exists, the description need not explain return values, and it covers the remaining gaps: modes, defaults, and the accounting/matching methodology. An agent has everything needed to invoke 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, but the description adds real meaning: it explains that quarter compares against the previous calendar quarter and what the superinvestor_cik switch actually changes (grouping by action, largest first, shares_change_pct in percent). This exceeds what the schema alone conveys.

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 curated superinvestors bought and sold in one quarter according to 13F') and delineates two distinct output modes based on superinvestor_cik. This is precise enough to distinguish it from siblings like get_stock_13f_holders or list_superinvestors 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?

Explicitly explains the conditional branching: omit superinvestor_cik for the cross-investor summary, provide it for individual moves. It also clarifies the default quarter behavior. It does not name a specific alternative tool for looking up a CIK, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so safety is covered. The description adds meaningful behavior beyond annotations: sorting by portfolio value, exclusion of options, Chinese name fields, and the predecessor CIK behavior. It does not contradict annotations, and the added context enriches the agent's understanding without relying on the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but each sentence earns its place: main purpose, data fields, sorting, naming, predecessor CIK, and alternatives. It is front-loaded with the primary function and avoids redundancy. Slightly long but not 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 parameters and an output schema present, the description covers all essential call-time information: what data is returned, sorting, edge case of source_cik, and pointers to sibling tools. It does not mention pagination or rate limits, but those are less critical given the tool's simplicity and the output schema's coverage.

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

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

The tool has zero parameters, so the baseline is 4. There is nothing for the description to add beyond what the schema provides (which is empty). The description appropriately explains the data structure instead, which is not parameter-related. No issues.

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: 'list the curated list of superinvestors' with detailed data fields (portfolio value, positions, filing date, top holdings). It clearly distinguishes from siblings by mentioning get_institution and get_superinvestor_activity for different needs, so an agent can tell it apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly directs when to use alternatives: 'Use get_institution(cik) for full holdings and get_superinvestor_activity for what they bought and sold in a quarter.' Also explains the source_cik caveat, leaving no ambiguity about when to use this tool versus 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 cover the read-only/idempotent/non-destructive profile, and the description adds substantial behavior beyond that: per-group result cap, best-match-first ordering, politicians sorted current-members-first, matching semantics (exact/prefix ticker, exact CIK/CUSIP, 2-char minimum for names), and the meaning of the `detail` field per group.

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 in the opening clause and every subsequent sentence carries non-redundant information. It is dense and somewhat run-on with nested parentheticals, which slightly taxes readability, 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?

Given an output schema exists, the description appropriately focuses on input interpretation and cross-tool routing while still noting the per-item `detail` and `url` fields. For a resolver feeding eight-plus siblings, this is complete enough for an agent to call it correctly and consume its output.

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 real meaning: it interprets `query` by spelling out how tickers, CIKs, CUSIPs and names are matched, and clarifies that names are SEC English names with Chinese-name matching for superinvestors/asset managers. `limit` is explained as a per-group cap, adding nuance beyond the schema's 'maximum matches per group'.

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 (find) and enumerates the exact resources searched (US stocks, 13F institutions/superinvestors, corporate insiders, politicians) with the disambiguating detail that it searches by ticker or name. It goes further by naming which sibling each returned identifier feeds (ticker→get_stock, institution cik→get_institution, etc.), so an agent can instantly tell it apart from the retrieval siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes its role clear as a resolver that yields the identifiers the other tools consume, giving strong context for when to reach for it first. It names the downstream siblings explicitly, but it does not state any exclusion or 'when not to use' condition (e.g. when to skip search and call a sibling directly).

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