Stockfacts

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond that: fields are null until loaded, each has its own last_updated, and it also reports last successful update timestamps, update schedule, and server usage limits. It omits nothing risky, though it doesn't hint at response size given the breadth of the payload.

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

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

A single ~250-word run-on sentence buries the actionable guidance ("Call it to check whether a date or quarter is covered") at the very end. The catalogue of datasets is defensible for an exhaustive coverage tool, but it is unstructured prose with no grouping or bullets, and a reader must wade through every dataset name to reach the point.

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 zero-parameter tool with an output schema, coverage is high: the description tells the agent what categories of coverage exist and that missing datasets appear as null. It is arguably redundant with the output schema in enumerating fields, and it could say more about what the agent should do with the answer, but nothing needed to call it 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?

There are zero input parameters, so per the rubric the baseline is 4. The description spends its words on output contents rather than inputs, which is harmless here since there is nothing to pass.

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 unambiguously what the tool returns: an inventory of which datasets exist (Form 4, 13F, 13D/13G, Form 144, congress trades, 10-K/10-Q/8-K, FINRA short interest, ATS, fails-to-deliver, market_caps, Taiwan/tw_ datasets) and their freshness. Among data-returning siblings like get_financials or get_insider_trades, it is clearly the metadata/coverage tool rather than a data-fetch tool, so the agent can separate it without inspecting schemas.

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 line gives explicit context: "Call it to check whether a date or quarter is covered." That is a clear trigger condition. It does not name alternatives or state when NOT to call it (e.g. that it returns no actual filing data and must be followed by the relevant get_/list_ tool), 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?

Far exceeds the annotations (readOnly/idempotent/non-destructive/closed-world): it discloses non-USD reporting currency and the usd_rate.average vs period_end conversion rules, filing/amendment provenance, Q4/single-quarter cash flows being derived by subtraction, unadjusted split/EPS caveats, ADR per-ordinary-share EPS, bank revenue caveats, multi-class share gaps, and the meaning of `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?

Front-loaded and information-dense, but the long parenthetical enumerations of individual line items (many with ellipses) are heavy and partially redundant given an output schema exists. A tighter description could carry the same semantic load with less bulk.

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 complex, quirky data tool the description covers the gaps that matter: currency conversion, derived periods, split/ADR/bank/multi-class exceptions, amendments, and when no statements exist. Since an output schema exists, return-value shape needn't be re-explained, and nothing an agent needs to interpret results 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 real meaning: it spells out that period=annual yields fiscal years and quarterly yields single fiscal quarters, what each `statements` value contains, and the currency semantics that govern how returned values must be interpreted.

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+scope: financial statements of one company sourced from XBRL in 10-K/10-Q/20-F/40-F SEC companyfacts. It names the concrete sections (income, balance, cash flow, shares) and explicitly distinguishes itself from get_stock for prices/valuation, so an agent can identify 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?

Gives clear operating context: period=annual vs quarterly semantics, statements selection, and explicitly routes the agent elsewhere for market cap ('get_stock has the company's market cap in USD'). It stops short of explicit when-not-to-use-it exclusions beyond the note about ETFs/funds having no statements, so not a full 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 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 cover the safety profile, and the description goes well beyond them: it explains default windows per section, the 200-row cap, publication lags (FINRA ~8 business days, ATS 2-4 weeks late), and disambiguates short interest vs. short volume vs. FTD vs. ATS. It also sets expectations on missing metrics (no float-based percentage).

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 section inventory, which is good, but the body is a dense wall of comma-separated field lists and parenthetical caveats that is hard to scan. Every claim is useful, yet the structure sacrifices readability for completeness.

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 four heterogeneous datasets, no output schema detail needed beyond what exists, idempotent read-only annotations, and one required ticker, the definition covers the nuances an agent needs: what each section means, timing/lag, row caps, and data limitations. 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 baseline is 3; the description adds meaningful semantics by spelling out what from/to do per section (each section covers the range, up to 200 rows) and what defaults apply when they are omitted — information not fully present in 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?

Names a specific resource and enumerates all four data sections with their fields, distinguishing it from list_short_interest (which is presumably cross-stock). An agent can immediately tell this is the per-stock short-selling dataset.

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?

Implicitly scopes usage to a single ticker and clarifies date-range behavior, but never names the sibling list_short_interest or states when to use one over the other. Guidance is strong on domain semantics but weak on tool 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds deep behavioral context: null/empty behaviors ('each is null when there is no data'), the full set of market_cap_unavailable reasons, delisting semantics with Form 25 dates, and quarter-completeness rules (45-day deadline, in_progress_quarter). 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?

The definition is a single very long paragraph that spends most of its length explaining return-value fields and their edge cases (split_factor, shares_mismatch, market_cap_unavailable reasons), much of which duplicates the existing output schema. It is front-loaded with the overview, but the volume and lack of structure work against conciseness.

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 complex multi-dataset aggregation tool, the description is thorough: it covers what is returned, how each figure is derived, edge cases (delisted, foreign filers, no price), and where to go for full lists. Nothing an agent needs to call it correctly is missing.

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

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

With a single 100%-covered parameter the schema baseline is 3, but the description adds real meaning by explaining that share classes are separate tickers (GOOG/GOOGL, BRK.A/BRK.B) because 13F reports them separately — directly relevant to how the ticker argument should be supplied.

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 scope ('Overview of one US-listed stock') and enumerates exactly which datasets the overview aggregates. It also names the sibling tools that return the full versions of each section, so an agent can distinguish it from get_insider_trades, get_stock_13f_holders, get_financials and get_short_interest.

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 routes the agent: 'Use get_insider_trades, get_stock_13f_holders, get_financials and get_short_interest for the full lists,' and notes screen_stocks lists companies by market cap. This is clear selection context, though it does not state hard when-not-to-use exclusions or prerequisites for calling 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?

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 cover read-only, idempotent, non-destructive, closed-world, so the bar is met; the description still adds substantial behavior: newest-first ordering, data since 2009, the 30-day market cap with a note when the range is narrowed, a 200-row-per-call limit with pagination, and that filing text is not stored. These are operational constraints an agent needs and none duplicate the annotations.

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

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

The material is front-loaded with the resource, but it is delivered as one dense run-on paragraph mixing scope, form taxonomy, output fields, retrieval guidance, and pagination. The mid-sentence catalog of 8-K item codes with descriptions is heavy for a description, and a few structural breaks would make it far easier to parse.

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

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

Despite an output schema existing, the description explains the row shape (accession, form, item codes, filed_date, accepted_at, period_of_report, ticker, url/sec_url/index_url) and how to retrieve underlying text, leaving no ambiguity for an 8-parameter, zero-required tool. Combined with the annotations, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so 3 is the baseline; the description goes further by explaining that items matches 8-K filings containing any of the given codes (and only 8-K/8-K-A have items), that forms includes amendments, and that ticker/cik should not both be given. It adds meaningful semantics over the schema, though much of the row-field detail belongs to the output shape rather than inputs.

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 (SEC filings: 10-K, 10-Q, 8-K, 20-F, 40-F with amendments) and both scopes (a single company or the whole market). It is immediately distinguishable from siblings like get_ownership_filings, get_financials, or get_major_holders, which cover different datasets. An agent does not need to open the schema to know what this returns.

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 conditional guidance: with ticker/cik the full company history is searchable (including former CIKs), without either the query covers the market but is capped at 30 days (default 7). It also directs the agent to sec_url / index_url for the actual filing text since Livermore stores none. It does not, however, name any sibling tool as an alternative when the agent wants ownership or financials instead, so routing between siblings 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 establish the safe read-only/idempotent profile, and the description adds substantial non-obvious behavior: rows with missing values and days_to_cover capped at 999.99 (dtc_capped true, days_to_cover null) are always listed last regardless of direction, thin stocks are filtered by default, there is no short-interest-as-%-of-float, and results are capped at 200 rows requiring paging.

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, default ordering and the pagination cap are front-loaded, and most sentences carry unique information (cadence, null ordering, absence of %-of-float). It is a single dense paragraph that could be broken into shorter units, 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, return values need not be re-explained, and the description still covers row contents, the recent_settlement_dates companion field, edge-case ordering, volume filtering and page limits. For a 6-parameter, paginated ranking tool this leaves nothing an agent needs 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 interpretation beyond the schema: the cross-parameter interaction of dir=asc with sort=change ('largest decreases (covering)'), the reason min_avg_volume exists, and the twice-monthly, ~8-business-day reporting cadence that governs settlement_date.

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

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

The description states a precise verb and resource ('Every stock's FINRA short interest for one settlement date ... ranked like livermore.club/en/shorts'), including the ranking dimension and scope, which clearly separates it from the single-company get_short_interest sibling. An agent can tell what the tool returns and how it is ordered 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 explains when the defaults are appropriate ('default: the latest' settlement date, default sort=change) and gives a concrete use signal ('dir=asc gives the largest decreases (covering)'), plus the rationale for min_avg_volume. It does not, however, explicitly name when to choose this over get_short_interest, so there is no hard exclusion or alternative 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 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes far beyond them: the exact market-cap formula (close x cover-page shares, split-adjusted), daily recalculation after close, the 200-row cap, and a full enumeration of why companies are silently absent (no_price, stale_price, no_shares, foreign_filer, shares_mismatch, out_of_range). The disclosure that GOOGL/BRK/META-class issuers are missing is exactly the kind of surprise an agent must know in advance.

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 correctly — sort order and filters come first, methodology and exclusions after. It is long, and the row-field inventory (ticker, name, exchange, ... url) partially duplicates the output schema, but the exclusion taxonomy genuinely earns its space because it flags non-obvious missing data.

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?

An output schema exists, yet the description still sketches the row shape, reports total/as_of semantics, and covers pagination limits and follow-up paths. Combined with the methodology and exclusion notes, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so 3 is the baseline; the description exceeds it by giving illustrative dollar values for a realistic screen and stating that either, both, or neither bound may be supplied. It adds usable intuition about bound semantics beyond the schema's terse 'inclusive / default: no maximum' phrasing.

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 opening clause gives a specific verb+resource+ordering: 'US-listed companies by market cap, largest first (dir=asc for smallest first)'. It is immediately distinguishable from siblings like get_stock (single company) or list_short_interest, and the optional cap-range scoping is stated up front.

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 supplies a concrete usage scenario ('For companies around $100 million, try min 50000000 and max 200000000') and routes the agent onward for deeper work ('follow up with get_stock, get_financials and get_insider_trades'). What it lacks is an explicit when-not-to-use or a named same-purpose alternative, but the screening context is unambiguous.

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.

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

Annotations already cover the read-only/idempotent safety profile, and the description adds substantial behavior the annotations cannot convey: data-arrival timing (quotes/institutional ~5:30 PM, margin/lending/foreign-holding ~10:30 PM Taiwan time), resulting nulls on the latest day, raw unadjusted prices and nulls on non-trading days, lot-to-share conversion, and the attribution/computed_by_livermore provenance requirement.

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?

It is front-loaded with purpose and the body is dense but almost every sentence carries operational value (timing, units, conventions, attribution). The trade-off is a single ~200-word paragraph for a two-parameter tool, which hurts scanability even though little is truly 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 available output schema, the description still supplies everything needed to call and interpret the tool: units (TWD, shares, _pct = percent), market codes (TWSE/TPEx), language and url caveats, null conditions, and licensing obligations. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema (code formats and the days range/default). The description reinforces ordering ('newest day first') and the 2021 start, but adds no syntax or format detail beyond the schema — the baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The opening sentence names a specific verb/resource and scope: 'Daily trading data of one Taiwan stock or ETF, newest day first (since 2021)'. It enumerates exactly what data groups are returned (price, institutional, margin, securities_lending, foreign_holding) and explicitly differentiates from the sibling tw_list_institutional_ranking, which 'ranks the whole market'.

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

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

It gives clear context for when this tool is the right one (single-stock daily price + chips data) and points at tw_list_institutional_ranking for market-wide ranking, plus the schema directs users to tw_search for code lookup. However, it never states exclusions against the other single-stock siblings (tw_get_stock, get_stock) or a 'do not use for X' caveat, so guidance is clear but not explicit about 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 cover the safety profile (readOnly, non-destructive, idempotent), yet the description adds substantial beyond-annotation context: derived Q4/Q2-Q3 figures via subtraction, check_failed accounting identities, non-annualized quarterly ROE, template-specific field availability, per-template revenue definitions, and the attribution license requirement. This is exactly the kind of data-quality disclosure 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 and period semantics, and nearly every clause carries information given the tool's complexity. However it is a single dense block with no structural separation, making it harder to scan than a tool this rich deserves.

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 complex financial-statement tool with an output schema already present, the description is remarkably complete: units (TWD, EPS per share), share/lot conventions, market codes, name language, derived-field semantics, and attribution obligations are all covered.

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

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

Schema description coverage is 100% and the period param's enum, default, and semantics are already documented in the schema, so the description largely restates them. It adds the ordering hint ('newest period first') but nothing else beyond what the schema provides for either parameter.

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 ('Financial statements of one Taiwan-listed company from the MOPS XBRL filings') with explicit scope, source, and coverage window (since 2013 Q1). An agent can immediately tell this apart from tw_get_monthly_revenue, tw_get_daily_trading, or tw_get_stock without opening a schema.

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

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

The description implies usage well (single-company statements, ETFs excluded, do-not-rank-revenue-across-templates) but never states when to pick this over siblings like get_financials or tw_get_monthly_revenue. It provides interpretation guidance rather than tool-selection guidance, so routing 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 cover safety (readOnly/idempotent/non-destructive), yet the description goes well beyond them: it discloses the data source and licensing obligations, distinguishes government open data from Livermore-computed fields (computed_by_livermore), specifies ordering rules (listed by market cap, then ESB/GISA which lack quotes), currency/unit conventions, and error behavior for unknown codes.

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 three modes are front-loaded and every clause carries information, but the single dense paragraph mixes tool-specific behavior with a generic 'Taiwan conventions' block that reads as boilerplate appended across the tw_ family, making it heavier than strictly necessary.

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 document return values, and it still covers scope, all three modes, ordering, localization (Traditional Chinese names/streams), attribution requirements, and error semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it explains how `chain` and `segment` interact to change the result shape, that `limit` applies per segment with listed companies ordered first, and that sub-segments carry parent_code.

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 (get) and resource (Taiwan's industry value chains from the TPEx platform), gives a concrete scope example (47 chains, semiconductors, D000) and the core use case ('to find companies by what they do'). It is clearly distinguishable from sibling tw_get_stock, which it explicitly names as the per-company counterpart.

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?

Enumerates all three invocation modes and their distinct outputs: no chain (all chains with code, name, company counts), chain (segments in platform order with companies), and chain+segment (segment plus sub-segments only). It also routes to the alternative (tw_get_stock shows the segments of one company) and notes that unknown codes return an error.

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?

Though annotations already cover the safety profile (readOnly, idempotent, closed-world), the description adds substantial behavioral context beyond them: it documents the error semantics for a non-trading date ("returns an error naming the latest trading day"), discloses exclusions (ETFs and untraded stocks omitted from rankings), notes who computed which fields, and states the attribution obligation under Taiwan's Open Government Data License.

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 is front-loaded, and most sentences earn their place (conventions, error behavior, attribution). The first sentence is nonetheless sprawling, bundling counts, rankings, and methodology into one long clause rather than breaking it into scannable pieces.

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?

An output schema exists, so return values need not be described, and the description still covers everything else an agent needs: date semantics, error behavior, unit conventions (TWD, shares, _pct), market codes, language of names, and the attribution requirement. Nothing material is missing for correct invocation.

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% for both parameters, and the schema already documents the date default and the 1-50/default-10 limit. The description restates the latest-day default and that limit means rows per ranking but adds no syntax or format detail the schema lacks, so the 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?

States a specific verb and resource (Taiwan market summary for one trading day) and enumerates exactly what is returned: TWSE and TPEx value traded, up/down/flat company counts, and three rankings. It also differentiates from siblings by naming tw_list_institutional_ranking for institutional net buying, so an agent can tell them apart without opening schemas.

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 is the latest day with quotes, and it explicitly routes the agent to tw_list_institutional_ranking for institutional net buying as an alternative. It does not, however, distinguish this from other likely-overlapping siblings such as tw_get_daily_trading, leaving some selection ambiguity.

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 safety profile, and the description adds substantial behavioral context beyond them: data starts January 2013, reporting deadline (by the 10th of the following month), that percentages are company-reported through MOPS rather than calculated by Livermore, ETF behavior (empty months with a note), and the attribution obligation under Taiwan's Open Government Data License.

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: the core purpose and return shape come first, followed by reporting cadence and conventions. The Taiwan-conventions paragraph is lengthy but every clause carries operational meaning (units, currency, naming, attribution).

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?

An output schema exists so return values need not be explained, yet the description still covers units, currency, naming language, attribution requirements, data start date, and the natural follow-up tool. Nothing needed to call it correctly appears to be 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 real semantic context for both parameters: it clarifies the data starts January 2013 (which bounds `months`), and explains the market/code conventions and TWD/percentage units that govern interpretation of `code`.

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 ('Monthly revenue of one Taiwan-listed company (TWSE or TPEx)') with exact field scope: revenue, MoM, YoY, YTD, and company_note. It is clearly distinguishable from the many sibling tools, and explicitly names tw_get_financials as the quarterly counterpart.

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?

Provides clear usage context: follow up with tw_get_financials for quarterly statements, and note that ETFs have no revenue data. It does not, however, state explicit exclusions against other sibling tools (e.g., tw_get_daily_trading) or when this tool would be the wrong choice.

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 readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: null semantics for missing data, the caveat that AI-written sections 'may contain errors' with annual_report_url as the authority, and a mandatory attribution/licensing requirement naming Taiwan's Open Government Data License. These are behavioral facts the agent cannot get from annotations or 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 purpose and organized by output section, which aids scanning. However, the long field-by-field enumeration of the response duplicates what the output schema already provides, so a meaningful fraction of the ~350 words does not earn its place; it is thorough but over-long for a one-parameter 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?

Given an output schema exists, the description need not restate return values, yet it still supplies the interpretive layer an agent needs: currency and unit conventions, percentage semantics, market codes (TWSE listed vs TPEx OTC), Traditional Chinese naming, and the attribution obligation. 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% and the single `code` parameter is fully documented in the schema, including formats and the tw_search fallback. The description adds only the general Taiwan conventions block (TWD, lots of 1,000 shares, _pct fields), which is mostly about output interpretation rather than the parameter itself, so the 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?

States a specific verb and resource ('Overview of one Taiwan stock or ETF (TWSE or TPEx) by code') and immediately enumerates the data sections it returns, so the agent knows exactly what it gets. It also distinguishes itself from siblings by naming tw_get_daily_trading, tw_get_financials, tw_get_monthly_revenue and tw_get_industry_chain as the tools for adjacent 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?

Explicitly routes the agent: 'For price history and daily institutional, margin, securities lending and foreign holding data use tw_get_daily_trading', and defers full statements to tw_get_financials and whole chains to tw_get_industry_chain. It also notes the ETF edge case ('ETFs and other securities usually have only security, quote and dividends'), which is real when-to-use 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 establish readOnly/idempotent/non-destructive, and the description goes beyond them with genuinely useful behavior: out-of-range dates fail with an error listing valid dates, ETFs are excluded, and attribution must be preserved for licensing with computed_by_livermore flagged as non-official. It does not cover auth or rate limits, so it is strong rather than exhaustive.

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 routing are front-loaded in the first two sentences, and the trailing 'Taiwan conventions' block is dense but earns its space by defining currency, lot size, and _pct fields. The single run-on paragraph is heavy and would scan better broken into short sections, which is the only reason it is not 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?

An output schema and annotations exist, and the description still supplies everything needed to call and interpret the tool: date window, enum meanings, per-row field definitions, units/currency conventions, language/URL caveats, and attribution obligations. Nothing material for correct invocation or interpretation 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; the description earns extra by restating category/side/days semantics in context and, more importantly, explaining what the parameterized period produces (net_shares as period total, estimated_value as summed daily net shares times close, period_change_pct measured against the base_date close). That adds meaning 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?

The opening sentence names a specific verb (bought/sold) and resource (Taiwan companies) and pins the exact scope: one investor category, 1/5/20 trading days ending on a date, companies only (no ETFs). It even distinguishes itself from the sibling tw_get_daily_trading by name, so an agent can route without opening either schema.

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

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

It states the operating window explicitly ('date must be one of the latest 30 trading days with institutional data (recent_dates); other dates return an error listing them') and names the alternative tool for a different task ('Use tw_get_daily_trading for one stock's daily history'). When-to-use, constraint, and alternative are all present.

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 adds substantial extra context: 100 rows per page, error behavior on unknown codes, the attribution/Open Data License obligation, currency and share-count conventions, and which fields are Livermore-computed rather than official.

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?

It is a long description, but it is front-loaded with the core screening behavior and each sentence carries distinct Taiwan-specific information (units, license, computed fields). Density is justified by the domain conventions, though it could be trimmed slightly.

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 returns, yet it still covers rows, industries, etf_count, conventions, and legal attribution. Nothing needed to invoke or interpret the tool 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 adds genuine meaning: industry 24 = semiconductors, 'etf' as a special sentinel, market values mapped to TWSE (listed) vs TPEx (OTC), and the default sort by market cap.

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: screening Taiwan companies listed on TWSE or TPEx (plus ETFs), with filter, sort, and pagination scope. It distinguishes itself from tw_get_stock, which it explicitly directs users to for full profiles.

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

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

Gives explicit when-to-use guidance: first call without industry shows available codes, unknown code returns an error, and for name_en/full profile use tw_get_stock instead. Alternatives and conditions are named directly.

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 only the safety profile (readOnly/idempotent/non-destructive), so the description carries the rest and does so richly: tiered matching order, company-before-ETF and market-cap ordering within tiers, the 2-character minimum, code normalization (2330.TW/2330.TWO), and the fields each result carries. It also discloses the licensing/attribution obligation and that computed_by_livermore fields are not official figures, which no annotation conveys.

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

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

Front-loaded with the core action, argument types, and follow-up tool in the first two clauses; the trailing conventions block (TWD, lots, _pct, Traditional Chinese, attribution) is long but each item is actionable for a Taiwan-market tool. Minor redundancy in enumerating result fields that the output schema already defines.

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 values, yet it still frames them usefully. Combined with the routing guidance, currency/unit conventions, and attribution requirement, an agent has everything needed to call and correctly present results from this 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 the baseline is 3, but the description adds real semantics beyond the schema: query normalization rules, the 2-character threshold for name matching, and the tier hierarchy that determines which matches win. It does not restate the limit bounds, which is fine since the schema does.

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

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

States a specific verb+resource+scope: find Taiwan stocks and ETFs listed on TWSE or TPEx that are still trading, by code, Chinese short/full name, or English name. It explicitly positions itself as the entry point that produces the `code` consumed by every other tw_ tool, which cleanly separates it from tw_get_stock and from the US `search`/`get_stock`.

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

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

Gives explicit when-to-use ('start here to get the code every other tw_ tool takes'), a named follow-up (tw_get_stock), and active exclusions ('Taiwan stocks are separate from the US tools (search, get_stock); TSMC's US ADR is TSM there'). An agent has no ambiguity about routing.

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