ticker-scout

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

Annotations only cover safety (readOnly/idempotent/non-destructive); the description adds substantive behavior: per-company fiscal calendars so each row carries its own period and dates, decimals-friendly units (actual dollars, per ADS, split-adjusted shares), FX conversion at the rate recorded per period, and the important non-failure contract that a company missing the figure or period gets an explanatory row instead of an error.

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 2-10 scope are front-loaded before the period and unit details. It's a dense multi-sentence block rather than a bulleted structure, but each sentence carries distinct information (defaults, period syntax pointer, missing-data behavior, units).

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

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

There is no output schema, so the description must carry the return contract, and it does: rows state their own period, dates, and source field; units and currency treatment are spelled out; and missing data is described as a row rather than an error. Nothing an agent needs to call or interpret the result 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 resolves what the schema's bare 'latest' default actually means (latest discrete period, quarter or newer fiscal year), explains that periods differ per company, and confirms the 2-10 ticker bound in prose.

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

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

States a specific verb (compare) plus the resource (2-10 companies) and the exact scope: one standard figure at a time. An agent can immediately tell this is the multi-company view rather than the single-company get_figure, and the figure vocabulary is anchored to a named sibling.

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

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

Gives clear operating context: it defaults to each company's latest discrete period, lists the period strings that select alternate windows, and routes figure naming to get_figure. It does not explicitly say 'use this instead of get_figure when comparing several companies,' which leaves the sibling boundary to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine value beyond them by disclosing the prediction caveat ('a prediction from filing history; a filing date is not an earnings date'), preventing a foreseeable misuse of the returned next-filing field.

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

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

One dense, front-loaded sentence that leads with identity then coverage contents, followed by a short parameter note. The enumerated field list is long but earns its place given there is no output schema; slightly run-on but no filler.

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

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

With no output schema, the description carries the full burden of describing return values and does so thoroughly, covering identity fields, source filings with their metadata, per-record URLs, and the prediction field. It also covers the optional `record` selector, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100%, with the `record` parameter already documented including accepted formats ('FY27Q1' or 'Q1 FY2027') and the pointer to list_periods, so the baseline is 3. The description's single sentence ('Pass `record` for an earlier record's manifest') restates rather than extends the schema.

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

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

States a specific verb and resource ('Company identity and coverage manifest') and enumerates the concrete data returned: name, CIK, exchange, incorporation state, SIC, fiscal period, source filings, published records, and predicted next filing. An agent knows exactly what this tool yields, though it never names the sibling it must be chosen over (e.g. get_company_metrics or list_companies).

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 only routing guidance is 'Pass `record` for an earlier record's manifest,' which is a parameter hint rather than a usage rule. There is no explicit statement of when to pick this over get_company_metrics, get_filings, or list_periods, so the agent must infer selection from the field list.

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, non-destructive profile, so the bar is lower. The description adds genuinely useful behavior beyond that: units are actual dollars not millions, shares are split-adjusted, foreign issuers are reported in USD, and requesting a period earlier than the data returns an explanatory result.

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

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

Dense but front-loaded: the kinds and their scope come first, defaults and unit conventions last. Each clause carries substantive detail, though the long parenthetical example lists make 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 no output schema, the description carries return-shape burden and does so reasonably: it covers units (actual dollars, split-adjusted, USD), the source of definitions, defaults, and out-of-range period behavior. It stops short of describing the record structure or how kinds are keyed in the response.

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

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

Schema description coverage is 100%, so the schema already documents ticker, kind and period including the enum and accepted period formats. The description restates defaults ('all', latest record) but adds no param syntax or meaning the schema lacks; the dollar/share/FX notes are output semantics rather than parameter guidance.

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

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

States a specific resource (company-reported measures outside GAAP statements) and enumerates the four kinds it returns (operating, non_gaap, bank, insurance) with concrete examples. The phrase 'outside its GAAP statements' cleanly separates it from get_financials/get_statements, so an agent can identify its scope 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 default behavior ('every kind this company reports', 'every period in the latest record by default') and explains the data source (the company's own definitions from filings or earnings releases). It does not, however, name sibling alternatives such as get_key_figures, get_margins_and_ratios or get_financials, so the routing among metrics tools is left partly to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds important context beyond annotations: it explains how omitted figures are handled ('never zeroed') and what kinds of uncertainties are surfaced. This is useful behavioral context about data semantics that annotations cannot 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 description is a single very long sentence with multiple nested clauses and parenthetical examples. While front-loaded with the core purpose, the dense structure makes it harder to parse than necessary. It could be broken into shorter sentences without losing content.

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?

Covers what the tool returns and why it matters, with no output schema to compensate. For a read-only metadata tool with rich annotations, this is nearly complete. Minor gap: it doesn't explicitly state whether the response is text or structured, but that is a small omission given the tool's nature.

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 are fully documented in the schema with examples and usage guidance. The description adds no parameter-specific information. Baseline 3 is appropriate when the schema does all the parameter work.

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

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

The description clearly states this returns the record's self-explanation: sourcing notes, coverage notes, uncertainties, and absent standard figures. It distinguishes itself from siblings like get_financials and get_statements by focusing on metadata about the record rather than the figures themselves. However, the opening phrase 'The record's explanation of itself' is abstract and could be more directly stated before the detailed enumeration.

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 states when to use it: 'to read before relying on an unusual figure or concluding one is missing.' This is a clear trigger condition that routes agents correctly away from sibling tools. It also implicitly covers what it is not for—getting the actual figures.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds real behavioral context beyond that: data is read from filings and exhibits, the default digest is short, items are dated and cite SEC accession numbers, and `record` yields a point-in-time snapshot. No pagination or rate-limit information, which keeps it short of a 5.

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

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

One dense paragraph that is front-loaded with what the digest contains before explaining the modifiers. It is slightly long, but nearly every clause carries information (topics, dating, accession numbers); only the parameter advice mildly overlaps the schema.

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

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

There is no output schema, so the description carries the return burden and does so: full digest by default, short, dated index alternative, point-in-time record. Combined with 100% schema coverage and read-only annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds value over the schema: it spells out the accepted topic vocabulary, notes that `section` accepts a heading with a unique prefix, and clarifies that `index` is dated and one-line. That is meaning beyond the raw field descriptions.

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

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

States a specific resource (digest of a company's material current reports, Form 8-K / 6-K) with a clear verb and then enumerates the contents (earnings releases, management changes, dividends/buybacks, debt, M&A, votes, restructuring, legal). An agent can distinguish this from raw-filing siblings like get_filings or get_narrative 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 describes default behavior (returns the full digest) and the conditions that select each variant: `section` to narrow, `index=true` for a one-line dated index, `record` for an earlier snapshot. It never names a sibling tool as an alternative, so the agent must infer whether to use get_events vs get_filings.

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 only cover safety (readOnly, idempotent, non-destructive); the description goes well beyond them by disclosing units (actual dollars, dollars per share, split-adjusted share counts), FX conversion at the recorded rate, restatement precedence when two records cover a period, and the exact error behavior. This is rich behavioral context an agent cannot get from structured fields.

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

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

Front-loaded with the core behavior in the first sentence, which is good, but the ~48-item enumeration of standard figure names is long and partly duplicates what the list_company_figures sibling is already cited as providing. The list aids discoverability but inflates length beyond what is strictly needed.

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

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

With no output schema, the description carries the return-shape burden and does so thoroughly: values lead with name_in_record and json_path, are never relabeled, and carry dates, form, accession, and a sec.gov link where tagged. Combined with units, FX, and period rules, an agent has everything needed to call and interpret 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 genuinely useful meaning: the full list of recognized standard figure names, the synonym/word-matching rule, case/space/underscore insensitivity, and the period='all' history ordering with newer-record precedence. It complements rather than merely repeats the schema.

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

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

States a specific verb+resource ('Get any figure for a company') and enumerates exactly what counts as a figure (revenue, EPS, FCF, a bank's CET1 ratio, a KPI), so the scope is unmistakable. It only differentiates against list_company_figures and never distinguishes itself from siblings like get_financials, get_key_figures, or get_company_metrics, so it falls short of full sibling disambiguation.

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 conditions for the three input modes (standard name/synonym, exact field name/path, or word-matching) and states the default behavior (every period in the latest record). It points to list_company_figures for enumeration and describes the no-match error, but offers no explicit guidance on when to prefer this over get_financials or get_key_figures.

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 closed-world, so safety is covered. The description adds genuinely useful behavior: default newest-first ordering, what each mode returns, that dashes in the accession are optional, and the search scope across published records. It stops short of auth/permission or pagination/rate-limit behavior, so not a 5.

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

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

Content is dense but nearly every clause earns its place, since with no output schema the enumerated return fields (form types, filing date, EDGAR index URL, document URL, uses) are load-bearing. The cost is that it is delivered as two sprawling sentences rather than structured mode blocks, which hurts scannability.

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

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

With no output schema, the description fully carries the burden of describing returns in both modes, including what 'every use' means and that full narrative/events text is returned for a single accession. Combined with the 100% schema coverage and the annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents all three parameters. The description goes beyond it by decoding an accession number (filer CIK, year, sequence) and clarifying that the format is the SEC's permanent ID and that dashes are optional, which meaningfully improves how the agent supplies the value.

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 (SEC filings behind a company's data) and cleanly splits the two modes: list every accession cited when `accession` is omitted, versus full detail on one filing when it is given. It also names the sibling `get_figure` and the condition that selects it, 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?

Explicit when-to-use branching on the `accession` parameter, plus the scope rule that all published records are searched unless `record` narrows it. It ends with a direct alternative routing ('For the sec.gov line behind one figure, use get_figure'), which is exactly the differentiation the sibling list demands.

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-open-world), and the description goes well beyond them: a whole-file call silently omits figure_sources, figure_sources yields a sec.gov link to the printing line, an unknown section name returns the valid list, section names vary per company, and all units/conversion rules are spelled out. These are non-obvious behaviors an agent could not infer from 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 content is front-loaded with what the tool returns, followed by usage rules and then units/conversion caveats, so the ordering is sound. It is dense and long — the units and foreign-issuer conversion material is useful but could be tightened — yet no sentence is padding.

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

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

There is no output schema, so the description must convey the return shape, and it does: statements, segment tables, per-share figures, notes, YTD/TTM columns, and the units of every figure. Combined with the section-selection guidance, an agent has everything needed to call and interpret 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 semantic value: it explains that section names differ per company, that omitting sections returns everything except figure_sources, and that requesting figure_sources by name returns source links. The record parameter's meaning is only hinted at via list_periods rather than explained in the description.

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

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

Opens with a specific verb-phrase identifying the resource ('Income statement, balance sheet and cash flow, already assembled from a company's SEC filings') and states the coverage window precisely. It explicitly distinguishes itself from get_statements ('for one statement or one period') and get_figure ('for one figure'), so an agent can route correctly without opening any schema.

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

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

Gives an explicit call procedure ('call with no sections first (or read available_sections) and then request only what you need') and names both alternatives with the condition that selects each: get_statements for one statement/one period, get_figure for a single figure. Both when-to-use and when-not-to-use are 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 and non-destructive, so the safety profile is covered. The description adds value beyond that by disclosing the payload shape (figures plus prose summary plus Q&A) and a relative cost signal ('Far smaller than get_financials'), which is genuinely useful for context budgeting. It stops short of mentioning auth, rate limits, or pagination, so not a 5.

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

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

Front-loaded with the return contents, then the routing rule, then the fallback sibling. The enumeration is dense but every element earns its place, and no sentence is wasted or redundant with the schema.

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

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

With no output schema, the description carries the full burden of describing returns, and it does so thoroughly (fields, prior-year comparison, provenance via accession number, plus summary and Q&A). Combined with the explicit sibling routing, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, and both parameters are fully documented there, including tag formats for record and ticker casing examples. The description only restates the record behavior ('Pass record for an earlier record's headline') without adding syntax or edge-case meaning. Baseline 3 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 concrete resource (headline figures for the most recent reported period) and enumerates exactly what comes back: revenue, net income, diluted EPS, prior-year value, YoY change, source record field, SEC accession number, plus a written summary and Q&A pairs. It also distinguishes itself from siblings by name (get_financials, get_figure), so an agent can route without opening any schema.

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

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

Explicit when-to-use ('Start here for any how did X do or how much did X earn question') and explicit when-not-with-alternative ('For any other figure, or a figure across periods, use get_figure'). It also covers the earlier-period case via the record parameter, leaving nothing 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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond that: it states which values are stored versus computed, that computed ratios are labeled with formula and source fields so they can be verified, and that a ratio is only produced when both figures fall in the same period of the same record — nothing is estimated.

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

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

Two sentences, front-loaded with the resource and its stored/calculated split; the trailing clause about period default is useful but partly duplicates the schema. Dense but nearly every clause carries information.

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

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

With no output schema, the description must explain the return payload, and it does: per-period margins and ratios, with computed values labeled by formula and source fields. The only missing piece is pagination/volume behavior for a potentially large multi-period response.

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 period and ticker formats are already fully documented in the schema. The description restates the default (latest record, all periods) without adding syntax or meaning beyond the schema's own period description, so the baseline of 3 applies.

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

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

The description names a precise resource — profitability margins and balance-sheet ratios — and splits it into stored metrics versus figures calculated on the spot, which an agent can use to tell it apart from get_financials or get_statements. It stops short of naming a sibling or stating an explicit contrast, so it is clear but not sibling-differentiating.

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 only usage information is the default scoping rule ('every period in the latest record by default, or the periods named by period'). There is no guidance on when to choose this tool over get_key_figures, get_financials, or get_segments, and no stated prerequisites.

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/closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: the default no-`section` call returns an index because 'the full document is large,' topic matching is fuzzy ('whatever this company calls them'), and 'legal' also pulls legal items from the 8-K digest. It does not discuss size limits or truncation of the 'all' response, which is the one remaining gap.

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 single dense paragraph rather than a scannable list, which slightly buries the index-first instruction, but every clause carries information: source disambiguation, index behavior, section/topic values, record, and the search_text hand-off. No sentence is filler.

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

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

With no output schema, the description carries the return-shape burden and does so: the index is described as 'every section with its size, first sentence and subsection headings.' Combined with the retrieval workflow and historical-record support, an agent has enough to invoke and interpret 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 already 100%, so the baseline is 3; the description goes further by explaining the semantics the schema only gestures at: prefix matching on headings, topic aliases mapping onto company-specific heading names, and 'all' as a catch-all. The `record` parameter's interaction with list_periods is also clarified, though no format examples are added beyond what the schema shows.

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 and resource: 'Qualitative synthesis of a company's latest annual and quarterly reports,' enumerates the covered sections, and explicitly states the source is the filings 'rather than from news.' It also names the adjacent sibling ('To find a keyword anywhere, use search_text'), so an agent can distinguish it from search_text and get_filings 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?

Gives an explicit two-step workflow (call without `section` to get the index, then pass a heading/topic/'all'), documents the `record` escape hatch for historical narratives, and routes keyword lookup to search_text. When-to-use and when-to-use-something-else are both spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds substantial behavioral context beyond that: that money is in actual dollars (not thousands/millions), that foreign issuers are converted at each period's recorded rate, and that splits are adjusted. This is meaningful disclosure of format and conversion semantics for a read-only tool.

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

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

The front-loaded 'How to read...' framing is effective, but the body is one dense, sprawling sentence-set with redundant restatement of units ('actual dollars, not millions' repeated in the closing paragraph). It is oversized for a metadata lookup and would benefit from trimming repetition.

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

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

There is no output schema, so the description carries the full burden of explaining return contents – and it does so thoroughly, enumerating every category of convention returned. Given its complexity and length, it is nearly complete, with only minor overlap and no pagination/shape notes.

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 are already documented in the schema, giving a baseline of 3. The description does not add syntax or semantics for 'ticker' or 'record'; it only indirectly references periods via list_periods, so no lift over 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?

The description opens with a specific framing – 'How to read a company's numbers before comparing or converting them' – and enumerates the resources returned (units, currency, ADR ratio, splits, fiscal calendar, accounting basis). An agent can tell this is a metadata/conventions lookup distinct from get_financials or get_statements. It lacks explicit sibling differentiation beyond the list_periods pointer, which keeps it short of a 5.

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?

'before comparing or converting them' clearly signals the moment to call this tool – ahead of comparison or conversion work, i.e. before compare_companies. It also routes the agent to list_periods for period dates. There is no explicit when-not or named alternative tool for the conventions themselves, so it stays at 4.

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?

Beyond the annotations (read-only, idempotent, closed-world, non-destructive), the description adds substantial behavior: table names vary by company and are echoed as the record names them, figures are in actual dollars rather than millions, shares are split-adjusted, foreign issuers are converted to USD, and a no-segmentation company returns a message listing the tables it does have.

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 in the first clause, and the dense parentheticals each carry distinct information (what each breakdown covers). It is a single long, somewhat run-on paragraph, but little of it is filler given the breadth of 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?

With no output schema, the description carries the return-value burden and does so: it names the three result sets, the period coverage, unit conventions, and the empty-result behavior. Nothing an agent needs to invoke and interpret this read-only tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning on top: it confirms the breakdown default of 'all', ties `period` to the company's own fiscal years and the latest-record default, and specifies the currency/adjustment conventions of the returned figures. This goes beyond restating 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?

The description states a precise verb+resource - how a company's results split as reported - and enumerates the three concrete breakdowns (segments, revenue_by_product, revenue_by_geography) with real-world examples (NVIDIA's Data Center, Apple's iPhone and Services). An agent can tell exactly what data comes back, though no sibling tool (e.g. get_financials, get_statements) is named to disambiguate the boundary.

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 sets the operative defaults ('Default: all three' breakdowns; every period in the latest record unless `period` names others) and describes the fallback when a company reports no segmentation. That gives clear context for calling it, but there is no explicit when-to-use/when-not guidance relative to the sibling financial-statement tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low, yet the description adds genuinely useful behavioral context: money in actual dollars, per-share figures per ADS for foreign issuers, split-adjusted share counts, FX conversion at the recorded per-period rate, derivation notes for ttm/ytd, and out-of-range period handling. This goes well beyond what the annotations supply.

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 first sentence front-loads what the tool returns and the rest is organized by parameter, so it reads well. It is nonetheless a dense wall of prose, and the out-of-range period rule is stated twice (description and the 'period' schema text), which is mild redundancy rather than padding.

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

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

With no output schema, the description carries the return-value burden and does: per-period dates, source form, accession, currency units, per-share treatment, FX conversion, and optional source links. Combined with 100% schema coverage and read-only annotations, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents all four parameters (including enum and defaults). The description still adds value by explaining the semantics behind omitted arguments (default = every statement/table held; default = every period in latest record) and what 'ttm'/'ytd' return with derivation notes, plus the sec.gov link behavior of include_sources beyond the schema's one-line note.

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-like resource and scope: the three statements, line items in reported order, for fiscal year/quarter/YTD/TTM. It is unmistakably clear what the tool returns. It does not, however, differentiate itself from sibling tools such as get_financials, get_segments, or get_key_figures, even though its default ('every statement and table held... including segments and industry metrics') overlaps with them.

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 rich: it explains how 'period' resolves (latest record, older-record search, 'ttm'/'ytd' blocks, out-of-range behavior) and how 'statement' defaults, so an agent knows what it gets when it omits arguments. What is missing is any explicit when-to-use-this-vs-alternative routing, e.g. against get_financials or compare_companies, and no when-not-to-use case.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds that the call takes 'No arguments' and, more usefully, enumerates what the guide actually contains, which is behavioral disclosure the annotations cannot provide given there is no output schema.

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

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

The call-to-action is front-loaded in the first sentence, and the long content enumeration is dense but each listed item earns its place by telling the agent what it will learn. Slightly list-heavy, but no wasted clauses.

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

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

With no output schema and no parameters, the description carries the full burden of explaining what comes back, and it does so item by item (period syntax, units, citation/linking to sec.gov, figure vocabulary). An agent knows exactly what this call yields before invoking it.

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

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

Zero parameters, so per the rubric the baseline is 4. The description correctly states 'No arguments,' which simply confirms the empty schema rather than adding semantics.

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 tool's role precisely ('How Ticker Scout's tools fit together') and enumerates the exact content it delivers: record vs. period, period syntax, units/currency, citation conventions, and figure vocabulary. This is unmistakably distinct from every data sibling like get_figure or get_financials, which retrieve data rather than explain the toolset.

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?

'Start here if unsure' gives a clear entry condition, and 'which tool answers common questions' positions it as a router to the other 19 siblings. There is no explicit when-not guidance (e.g., skip this if you already know the period syntax), which keeps it just short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real value by disclosing the shape and breadth of the payload (per-company records plus an aggregate coverage summary) and the data-source scope. It omits return format details such as ordering or truncation for a ~500-company list, which is the main remaining gap.

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 what the tool returns, then the when-to-use rule, then the scope definition — a sensible ordering. The opening sentence is a long comma-chained enumeration, but every clause corresponds to actual returned content 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?

There is no output schema, so the description carries the burden of explaining returns — and it does, listing the per-company fields and the summary block. Combined with the stated coverage domain and the 'call this first' entry-point role, an agent has everything needed to call it correctly with or without a filter.

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 single `query` parameter already has a full schema description covering matching fields and case-insensitivity (100% coverage). The description never mentions the optional filter, so it adds nothing beyond the schema here; baseline 3 applies.

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

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

States a specific verb and resource ('The public companies Ticker Scout covers') and enumerates exactly what each record carries (latest fiscal period, published records, predicted next SEC filing) plus a coverage summary. It also defines the scope boundary ('S&P 500 plus major foreign issuers that file with the SEC'), which no sibling tool provides.

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 invocation triggers: 'Call this first when you do not know whether a company is covered, or to turn a company name into a ticker.' That's clear positive guidance, but it doesn't name an alternative (e.g. get_company when you already have a ticker), so the when-not case 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is free to add operational behavior — and it does: default period scoping differs between listing (latest FY + latest quarter) and search (every period in the latest record), plus the edge-case that an out-of-range period returns a 'data does not go back that far' message. It does not describe result size or truncation limits.

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 listing/search distinction is front-loaded in the first two clauses, followed by concrete examples. Dense and mostly waste-free, though the middle sentence packs several clauses (grouping, examples, keying) into one long construction that slows parsing.

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

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

With no output schema, the description carries the full burden of describing the return shape, and it does: standard_figures maps standard figures to company-specific names, other_figures groups remaining figures by statement/table keyed by path with values. Combined with defaults and error behavior, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine semantics: `query` matches only when field names contain every word (AND semantics, not substring OR), `block` limits to a single table, and `period` defaults differ by mode. These clarify behavior the schema wording leaves ambiguous.

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 ('Discover which figures a company's record holds and what it calls them') and immediately differentiates itself from retrieval siblings by noting every returned name/path can be passed to get_figure. It also distinguishes the two operating modes (listing vs. query), so an agent can place it precisely among 19 siblings.

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

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

Explicitly frames when to use each mode: without `query` for full discovery, with `query` for targeted name matching, `block` to narrow to one table, and `period` for non-default periods. It names get_figure as the downstream alternative, but gives no explicit when-not guidance against siblings like get_financials, get_statements, or get_key_figures.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: it explains the fiscal-calendar semantics ('Fiscal years are the company's own' with NVIDIA/Apple examples) and the 52/53-week-year nuance, which materially affects how an agent interprets returned periods. It stops short of stating return format or ordering, but this is useful added context.

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 scope statement is correctly front-loaded, but the body is a single semicolon-chained run-on enumerating many fields with no visual structuring, which is hard to scan. The content largely earns its place given the absence of an output schema, but the packaging is dense and monotone.

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

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

With no output schema and no annotation detail on returns, the description carries the full burden and does so: it enumerates the period fields, the YTD/TTM blocks, the fiscal year end, the week-based-year flag, and the published-records list with their permanent URLs. Combined with the fiscal-calendar explanation, an agent has what it needs to use and interpret the result.

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

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

One parameter at 100% schema coverage, so the schema already documents the ticker and its case-insensitivity with examples. The description adds no parameter-level detail beyond that, which is the expected baseline 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?

Opens with a concrete scope statement ('How far back the data goes for one company: every fiscal year and every quarter'), which is a specific resource with clear framing, and enumerates the payload (period dates, source form/accession, YTD/TTM blocks, fiscal year end). It does not explicitly differentiate itself from near neighbors like get_filings or get_company, which also touch filings and company metadata, so 4 rather than 5.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternative tools such as get_filings or list_upcoming_filings. An agent must infer that this is the tool for enumerating reporting periods from the name alone.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description rightly spends its budget on semantics instead: results are predictions from filing history rather than announced dates, ordering is soonest-first, and the period currently held is returned. It adds real interpretive value, though it says nothing about result volume or pagination.

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 scope and ordering, then the caveats and the sibling pointer, in four tight sentences. Every sentence earns its place, including the earnings-date warning, which prevents a concrete misinterpretation.

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

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

With no output schema, the description carries the return-shape burden and does so: predicted date, form, and period currently held, in soonest-first order. Combined with the prediction caveat and sibling routing, an agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100%, so both parameters (days, form) are already documented in the schema. The description restates the day window and implies the form filter through its form list, but adds no format or default detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource+scope: every covered company expected to file a 10-Q/10-K (or 6-K/20-F) within N days, sorted soonest first, with predicted date/form/period. It also names the sibling that covers the single-company case (get_company), so an agent can distinguish it without opening another 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?

"Use it to see whose data refreshes soon" gives the triggering intent, and "One company's next filing is in get_company" explicitly routes the alternative case. It further warns that a filing date is not an earnings date, preventing a plausible misuse.

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

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

Annotations already carry the read-only/idempotent/non-destructive profile, and the description adds substantial behavior beyond that: case-insensitive matching, quoted-phrase exact matching, AND semantics ('every word of the query'), best-first ranking, the ranked most-mentioned-sections list, full passage text with section and subsection, and default coverage of all three documents.

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 first clause and the return shape follows immediately; every sentence carries information. The trailing example list is long (seven examples) and slightly dilutes an otherwise tight, well-ordered paragraph.

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

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

With no output schema, the description carries the full burden of describing returns and does so completely: passages in full with section/subsection, ranking order, and the ranked section list. An agent has everything needed to call it and interpret results.

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

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

Schema description coverage is 100%, so the schema already documents ticker, query, record, limit and documents, including defaults and bounds. The description restates the document categories and query syntax rather than adding new semantics, so the baseline of 3 applies.

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

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

Specific verb ('Find') plus resource ('what a company's filings say'), immediately scoped to a keyword search across three named document sets. It is clearly distinguishable from get_narrative/get_events, which it positions as the follow-up readers for whole sections.

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 search context (keyword lookup across filings) and explicitly routes the agent onward to get_narrative or get_events to read a matched section whole, plus list_periods for record discovery. It never states when this tool is the wrong choice (e.g., vs. get_filings for raw documents), so it falls short of full when/when-not coverage.

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