MetricDuck — Financial Analysis

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), and the description adds real context beyond them: filing counts only include filings whose section text was extracted, with a pointer to list_filings for the full history. It also enumerates the return contents, which matters since there is no output schema.

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

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

Front-loaded with trigger phrasings and return contents, then alternatives, then next calls. Well-structured and every sentence carries routing or coverage information, though the multi-paragraph layout is on the longer side for a two-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?

With no output schema, the description compensates by enumerating the return payload and its caveat about extracted-text coverage. Usage, alternatives, and next steps are all present, so an agent has everything needed to call and follow up correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters including the CIK-preference note for delisted companies. The description only restates that it accepts a ticker, name, or CIK, adding no format or matching nuance 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 (browse/retrieve) and resource (company) with the exact scope: identity, filings with extracted text, signals, indexed date range, and next calls. It is clearly distinguishable from siblings like get_company_overview and search_companies because it names what it returns that they do not.

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

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

Opens with the user phrasings that trigger it ('what filings do you have for X?') and explicitly routes other intents: search_companies for picking among name candidates, screen_companies/screen_filing_signals for screening, search_sec_filings for themes. When-to-use and alternatives are both stated, not inferred.

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

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

Goes well beyond the readOnly/openWorld annotations: discloses the period-end LOCF pricing rule (multiples are NOT at today's price), that row dates can differ across peers by a quarter, that sector-inapplicable metrics are omitted, that Q annualized ratios are suppressed, and that responses cap at ~20K chars. The 10-peer cap and its failure mode ('returns the limit and the count you asked for, so retry') is exactly the kind of operational detail agents need.

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 trigger, then bulleted peer_mode rules and three concrete use-case call examples — well structured and skimmable. It runs long and repeats the 'Data through'/period-end point that the schema partly covers, so it is dense rather than tight.

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 5-param, no-output-schema tool, everything an agent needs is present: peer selection modes, period semantics, metric selection and its fallbacks, size caps, and where to go for data this tool deliberately does not provide.

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 still adds real value beyond it — the custom_peers cap and its retry behavior, and the metrics-subset workaround for the response-size limit. Most other parameter guidance (peer_mode, period_type semantics) duplicates the schema text rather than extending it.

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

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

States a specific verb+resource (side-by-side comparison table of ~70 metrics with peer ranks on ROIC/margin/growth) and immediately differentiates from screen_companies and get_metric_history. An agent knows exactly what this returns versus its 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?

Opens with an explicit trigger ('when the user asks how a company compares with its peers or named rivals'), names the two alternative tools and their scopes, and explains when to pick peer_mode='sector' vs 'tags'. It even routes the agent elsewhere (get_stock_price + get_metric_history) for as-of-date or custom-definition multiples.

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 (readOnlyHint, destructiveHint false), so the description focuses on richer behavioral context: coverage-dependent output, Source tiers (SEC-filed vs Issuer-published vs Machine-transcribed), and explicit NO_TRANSCRIPT / WAITING gaps. It also notes transcripts are management commentary, not SEC-filed facts. No pagination/rate-limit detail or return-shape caveats beyond the tiering, 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?

Front-loads the core question and the routing to siblings effectively, but the model-alias parenthetical and the long output description (multiple table types plus per-quarter arrays) are dense and partially redundant. The structure is organized (routing, output, use cases, sibling) but less tight than it could be.

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 4-param tool with no output schema, the description covers return structure (coverage table, trajectory table, guidance deltas, qualitative arrays, drill hints), the transcript Source tier concept, and known gaps. It is close to complete for an agent to invoke and interpret results, though the exact shape of the per-quarter arrays depends on requested dimensions and isn't fully pinned.

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 ticker, dimensions enum values, n_quarters bounds and vantage_date pattern. The description adds value by enumerating the 13 dimensions with their per-quarter series semantics and by explaining the vantage_date intent ('window anchored there rather than today'). This is useful supplementary semantics beyond the schema, though it largely restates the enum list.

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 ('compare earnings calls', 'cross-quarter trajectory view of transcript signals for a single ticker') and explicitly distinguishes itself from sibling get_filing_section for single-call verbatim text. The aliases (get_earnings_call_transcript etc.) and the routing line to screen_filing_signals make the scope unambiguous.

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?

Names concrete alternatives and the conditions that select them: drill into get_filing_section for one call's verbatim remarks/Q&A, and use screen_filing_signals for signal changes across many companies between two windows. Three worked use cases reinforce the when-to-use.

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, but the description adds crucial behavioral context: empty results do not mean no IR events, last_checked_at defines freshness, fallback to 8-K Item 2.02 filings, and the non-point-in-time nature of upcoming vs past buckets. These are beyond what the 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 long but tightly structured and front-loaded, with bullets for common questions, return fields, coverage caveats, and alternatives. Every section carries routing or caveat information that helps correct invocation.

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?

Although there is no output schema, the description enumerates the returned event fields, material chip semantics, freshness metadata, fallback behavior, and point-in-time limitations. This is complete enough for an agent to call the tool correctly and interpret its 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 coverage is 100% and the sole ticker parameter is fully documented in the schema. The description does not add syntax or constraints beyond that, so the baseline of 3 for high schema coverage is appropriate.

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

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

The description states a specific verb and resource: retrieve a company's IR event calendar, covering both upcoming and past events. It distinguishes itself from siblings by explicitly routing materials-text questions to get_ir_documents and management-commentary questions to compare_earnings_calls.

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 explicit example questions that select this tool, explains when the fallback SEC filing list appears, and names alternative tools for adjacent needs. The when-to-use guidance is concrete and leaves little 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 declare a read-only, open-world, non-destructive call, so the description isn't needed for the safety profile. It adds genuinely non-obvious behavior: latest snapshot only, no point-in-time semantics, restatements/recasts served under the as-of citation, and that LOOK-AHEAD flags cover only later amendments of a period's own filing. The restatement caveat is valuable but dense and partly framed around sibling tools rather than this one's response.

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 lead sentence and the 'Includes:' block are well front-loaded and scannable. The third paragraph, however, spends substantial length on restatement/look-ahead mechanics and on how to pin get_xbrl_facts to an accession_number — guidance about other tools that dilutes this tool's core message.

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, but the 'Includes:' enumeration effectively describes the return payload field-group by field-group (valuation, profitability, cash flow, balance sheet, capital allocation, segment mix, earnings insights, flags). Combined with the scope and time-boundary caveats, 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% and the `depth` enum already carries detailed preset semantics, so the schema does the heavy lifting. The description never mentions `depth` at all, even though the response shape varies by ~2K vs ~9K+ chars — that is the one parameter where a hint would have helped. Baseline 3 for a fully documented 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 (a one-call snapshot of price, valuation, margins, cash flow, balance sheet, segments) and enumerates exactly what is included. It explicitly distinguishes itself from get_financials, get_metric_history, and get_stock_price, so an agent can pick it without opening sibling 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?

Opens with the triggering condition ('when the user asks for a quick read on one company now') and then names alternatives with the conditions that select them: get_financials for multi-period, compare_companies for peer benchmarking, get_stock_price for historical/as-of closes, get_xbrl_facts for segment history. It also states the exclusion clearly ('Not point-in-time').

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 the safety profile (readOnly, openWorld, non-destructive); the description goes well beyond them by disclosing the receipt/deep-link mechanism, that unreceipted figures still appear and are not evidence of error, the non-GAAP-adjacent nature of management figures, and the abbreviation discrepancy in the rendered table versus <raw_data>.

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-loads the core purpose and then layers distinctions, use cases, and caveats in clearly headed blocks; nothing is filler. It is on the long side and restates the point-in-time/vantage semantics and the sibling distinctions more than once, which keeps it just short of a 5.

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

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

With no output schema, the description carries the burden of describing returns and does so: the exact income-statement and cash-flow lines, growth figures, and the per-figure deep-link plus verbatim quote. The non-GAAP precision caveat and the exactness warning close the remaining gaps for this tool's complexity.

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: it specifies that vantage_date bounds which releases are visible, that quarters walks back from the vantage rather than from today, and that a revised release is a new accession with no restatement look-ahead. That meaning is not derivable from the schema alone.

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 8-K's headline income statement ... as-released cash flow') and enumerates the exact fields returned (revenue, operating income, net income, diluted EPS, OCF, capex, FCF). It explicitly separates itself from get_financials, get_company_overview and get_earnings_reports, 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?

Gives an explicit trigger ('when the user asks what a company just reported in its earnings release'), names the three nearest alternatives with the condition that selects each, and supplies two worked Use Cases with parameter values. When-to-use and when-not-to-use are both covered.

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 safety (readOnly, openWorld, non-destructive) but the description adds far more: per-cell coverage states (present/pending/none), exact fiscal-period deck joins, a ±1d single-candidate webcast match, the important caveat that a missing webcast is not evidence no webcast was held, and a not-point-in-time disclaimer pointing at vantage_date tools. This is exactly the behavior an agent needs to avoid over-reading results.

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 concept before examples, and the routing block is scannable. It is dense and longer than typical, with three example phrasings that partially overlap, but essentially every clause carries distinguishing or caveat 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?

There is no output schema, yet the description conveys the row shape (artifact cells with present/pending/none states), the joins used, and known data gaps. An agent can call this and correctly interpret the result without further documentation.

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

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

Schema coverage is 100%, so ticker and limit are already documented including the default of 12 and newest-first ordering. The description's 'one row per fiscal period' framing clarifies what limit counts, but does not add syntax, formatting, or edge-case guidance 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 resource with its granularity: a per-fiscal-period document index, one row per quarter/year, aggregating 8-K, transcript, 10-Q/10-K, deck, and webcast. It then explicitly disclaims being a figures tool, which cleanly separates it from get_earnings and get_financials.

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 three concrete user-phrasings that should route here plus a full negative routing list (numbers → get_earnings, XBRL → get_financials, calendar → get_company_events, slide text → get_ir_documents, call commentary → compare_earnings_calls). Nothing is left to inference about when to select this tool versus a sibling.

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

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

Annotations already establish read-only/safe/open-world, so the bar is lower, yet the description adds real behavioral context beyond them: 'Only the LATEST filing is indexed', facts are presented neutrally with LLM-derived ones labeled, each fact carries evidence plus a pointer to the next section, and vantage_date enables point-in-time backtesting. These are non-obvious constraints an agent could not infer from annotations.

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

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

Front-loaded with the core purpose and use cases before the dense 8-K rerouting paragraph, and every sentence carries weight. The second paragraph is long and heavy on cross-tool routing detail, which makes the body denser than strictly necessary for this single tool, but nothing 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?

No output schema exists, so the description carries the return-value burden and does so: it explains the returned facts include evidence and a next-section pointer, notes neutrality and LLM labeling, discloses the latest-filing-only limitation, and covers the optional lens and vantage_date. 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%, so the enum semantics of lens and the vantage_date format are already documented; the description mostly reinforces rather than adds. It does add usage-level meaning by pairing lenses with concrete scenarios (ENPH accounting red flags, UNH risk trajectory), which helps an agent pick the right lens 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 verb (returns the extracted facts) and resource (a signal index over the latest 10-K/10-Q), and enumerates the substantive domains covered (red flags, accounting quality, debt/liquidity, risks, tone, segments). It clearly distinguishes itself from get_filing_section, list_filings, and compare_earnings_calls by naming what each of those is for instead.

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 (user asks what matters in a company's LATEST 10-K/10-Q), explicit when-NOT-to-use (prior-quarter KPIs, guidance, beat/miss questions), and names the alternative workflow with concrete call syntax (list_filings(form_subtype="8-K-earnings") then get_filing_section). It also routes cross-quarter earnings-call trends to compare_earnings_calls.

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, destructiveHint=false and openWorldHint, so safety is covered. The description adds retrieval behavior beyond that: pagination semantics, the outline-mode fallback for multi-exhibit 8-K/DEF 14A, and the fact that omitting accession_number defaults to the latest filing. Much of this repeats the schema rather than extending it, 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?

Front-loaded with scope and mode selection, then use cases, then sibling routing — a sensible priority order with bold headers. It is long, but the length is earned by a 17-parameter tool with zero required params, and each use-case line maps a real prompt to a call.

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

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

For a 17-param, no-output-schema tool, the description supplies mode selection, default behavior, id catalog references, fallback behavior, and sibling routing. An agent can construct a correct call for common questions without further inference.

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 genuinely extends meaning: it explains the section_id-omitted outline mode, gives valid-id categories with gotchas (no human_capital id; table_* vs prose-only footnote_*; company-wide vs per-segment cost lines), and shows which param combination answers which question. It is documentation layered on top of, not merely 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?

States a specific verb+resource ('Read Filing Section') and immediately bounds the scope: 10-K/10-Q/8-K content, proxies, and earnings-call transcripts. It distinguishes itself from siblings by naming list_filings, search_sec_filings, compare_earnings_calls and get_ir_documents with the conditions under which each is preferred.

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 coverage via concrete example prompts mapped to parameter combinations, plus a 'Related:' block that routes the agent to alternatives (trends -> compare_earnings_calls, slide-deck KPIs -> get_ir_documents, missing figure -> search_sec_filings). The two retrieval modes are also framed as a choice with a selection rule.

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 beyond the annotations' readOnly/openWorld profile: it discloses the ~20K char response cap and the exact truncation rule (oldest periods trimmed first, same count per statement, whole statement dropped only if nothing fits), that citations resolve to EDGAR index handles, and that vantage_date bounds visible FILINGS rather than reconstructing historical values.

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 when-to-use line, then use cases, then output caveats — a sensible hierarchy. It is long and repeats some vantage_date/look-ahead material already present in the schema description, which costs a point, but nearly every sentence carries operational 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 still explains the return surface (markdown table vs. <raw_data>, footnote citations, defaults), the precision trap (table abbreviates to $10K/$10M quantisation; quote <raw_data> for tie-outs), and the truncation escape hatch (request fewer statements for more periods).

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 would be 3; the description earns above baseline by mapping natural-language intents to parameter combinations ('MSFT revenue trend 5 years' -> period="annual", years=5; 'Is Tesla's debt increasing?' -> statements=["balance"]) and restating the default of all three statements quarterly for two years.

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 framing ('income statement, balance sheet or cash flow over several quarters or years: all three statements in one call, up to 10 years, each period cited to its filing') and explicitly distinguishes itself from the two closest siblings, get_metric_history and get_company_overview, in the same sentence.

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 routing (quantitative history here vs. get_filing_index/get_filing_section for qualitative risks, accounting quality, management tone), plus excluded cases (Adjusted EBITDA must be read from the issuer's filing) and four concrete user-query-to-parameter mappings.

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 safe-read profile (readOnlyHint, destructiveHint=false), yet the description goes far beyond: it discloses basis-matching rules (non-GAAP never compared to GAAP), typed failure statuses (no_actual_on_basis, not_yet_settled, etc.), coverage notes, and the deliberate refusal to emit a verdict. It also flags the non-point-in-time join behavior, which 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?

Front-loaded with the core question and organized into Use Cases / Output / caveat sections that are easy to scan. Slightly long and with some overlap between the opening 'returns both sides verbatim' line and the Output bullets, but nearly every sentence carries distinct 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?

There is no output schema, so the description carries the full burden of describing return shape, and it does so thoroughly: guidance items, actuals, comparison with range_position/delta or typed status, and coverage notes. 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 baseline is 3, but the description adds real meaning: it explains how fiscal_period resolves when omitted (most recent SEC-filing period, or a newer quarter whose 8-K release targets it) and demonstrates usage in the examples. It does not add further syntax or format detail beyond that.

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 precise verb+resource: joining forward guidance from earnings-call transcripts to reported actuals from 10-K/10-Q and 8-K filings for the same ticker and fiscal period. It is clearly distinguishable from siblings like get_earnings and get_financials, which it explicitly contrasts on the point-in-time dimension.

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 three concrete use cases with example invocations, explains the fiscal_period default, and names the alternatives to use for as-of/point-in-time work (get_earnings, get_financials with vantage_date). When-to-use and when-not-to-use are both 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 cover only the safety profile (readOnly/openWorld/non-destructive), but the description adds substantive behavior: the return shape (title, IR url, stable gcs_uri, slide text cited by page), the default when query is omitted ('bounded prefix of the latest deck'), and a genuine mode caveat ('In list mode `query` is ignored'). No output schema exists, so the description rightly carries the return-value burden and does so well.

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 differentiator is front-loaded in the first sentence, followed by when-to-use and then examples. It is well organized, though the three 'Use Cases' lines partially restate the query guidance given just above, so a small amount of redundancy keeps it short of 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?

For a 6-parameter, no-output-schema tool, the description supplies everything needed: what each response contains, default behavior with no query/period, the list-vs-full distinction, and resolution by ticker or cik. No material gap remains for an agent 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 description coverage is 100%, so the baseline is 3; the schema already documents query's whole-word AND semantics and mode's full/list behavior. The description adds concrete query exemplars ('production guidance', 'berth'), the combined fiscal_period form ('2024Q3'), and the ticker-or-cik resolution rule, which gives mild extra value beyond the structured fields.

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 (retrieve IR earnings presentation deck text) and immediately scopes it against siblings: content 'ONLY in the company's investor-relations slide deck and NOT in the SEC 8-K/10-Q release text or XBRL.' An agent can distinguish this from get_filing_section, get_xbrl_facts, and get_metric_history 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?

Explicitly names the trigger condition and alternatives: 'Reach for this when get_metric_history / get_xbrl_facts have no series for a KPI or guidance figure, or the 8-K earnings release from get_filing_section lacks it.' It also enumerates the content types (guidance ranges, segment outlook, chart KPIs) that select this tool, 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 establish read-only/open-world safety, but the description adds substantial behavioral context: newest-first rows, fiscal labels vs calendar period_end, filing citations, consolidated-only limitations, the earnings-season FY gap, and vantage_date look-ahead caveats. It does not contradict 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 description is long but well structured and front-loaded, moving from primary use to examples to exclusions and caveats. Given the tool's complexity and the important edge cases, most sentences earn their place, though some repetition between the prose and schema descriptions 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?

For a metric-history tool with no output schema, the description covers return ordering, label interpretation, citations, consolidated-only scope, and next-best alternatives. An agent has everything needed to call it correctly 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: metric_id catalog behavior on misses, sector-specific NULLs, custom-multiple guidance, and the important limitation that vantage_date bounds existence/citation but not the as-known value. It is strong, though much of the per-parameter detail is already 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?

The description states a specific verb/resource: retrieving one metric for a company over a period or series. It explicitly distinguishes itself from siblings by noting that get_financials returns whole statements and compare_companies sets a company beside peers.

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 explicit when-to-use examples, names alternatives for by-segment series, issuer KPIs, and specific-date prices, and states that consolidated values are the only option here. The routing guidance is unusually complete.

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 safety (readOnly/openWorld/non-destructive), and the description adds substantial non-obvious behavior: lazy one-level-per-call drill-down, that 'derived' inputs point to their own lineage while 'base' inputs are XBRL facts, and that non-computed metrics return a message pointing to get_xbrl_facts. This is context the 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?

Front-loaded with the core definition, then structured into drillable behavior and use cases. Every section earns its place, though the length is on the longer side for what remains a fairly simple read operation.

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?

No output schema exists, yet the description explains the return structure (formula + inputs with source), the drill affordance, and the base-case fallback. An agent has everything needed to call it correctly 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 coverage is 100%, so the baseline is 3, but the description adds meaning: it explains the metric param must be a COMPUTED metric, and demonstrates segment/fiscal_year/fiscal_period usage in the audit example. It adds value beyond the schema, though it does not fully re-specify every 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 (derivation) and resource (computed metric lineage: formula + immediate inputs), with clear scope ('one level at a time'). It explicitly distinguishes itself from siblings by naming get_metric_history, get_company_overview, and get_xbrl_facts as the alternatives for the value itself.

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 'call it ONLY when' conditions (how a metric is computed, which definition, verify/audit) paired with the exclusion ('NOT to get the value itself') and named alternatives. Three concrete use-case examples map queries to calls.

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 the safe-read profile (readOnlyHint/openWorldHint/destructiveHint), so the description must carry the rest — and it does: rows exist only on trading days, coverage is ~8,400 US common-equity tickers, end-of-day only (no intraday/options/FX), deep pre-2014 history may be sparse, returns are point-to-point not total return, and the ~20K-char reply cap plus `Next:` continuation behavior are disclosed.

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 a clean bulleted date-semantics section, then use cases and coverage notes — every block earns its place. It is long and partially redundant with the equally verbose start_date/end_date schema descriptions, which keeps it just short of 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?

There is no output schema, so the description must describe returns, and it does: first/last close, period return on both close and adj_close bases, latest reported shares outstanding and implied market cap, plus how they should be used in market-cap/EV/P/B math. 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 interpretation beyond the schema field text: which row counts as 'the price on/after' vs 'on/before' a date, the weekend/announcement landing case, and the strategy of two narrow calls instead of one wide window. Much of this is echoed in the schema descriptions, so it is additive rather than essential, but it is genuinely clarifying.

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 states a specific verb+resource+scope: daily end-of-day close, adj_close and volume for US-listed stocks from a market-data feed, explicitly 'not SEC filings'. It also names and distinguishes the two nearest siblings (get_company_overview shows only latest price; get_metric_history has period-end multiples), so an agent can route without opening any other 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 explicit when-to-use rules with concrete examples ('AAPL close on 2025-07-28', a two-call point-to-point return, event-relative windows, no-dates case), plus the when-not signal (not SEC filings) and the cheaper two-narrow-window alternative to a wide window. Alternatives and their selecting conditions are all named.

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 and open-world safety, but the description adds substantial behavioral detail beyond them: sign semantics for as-filed values, caveats on filed-negative hints, concentration tagging behavior, and distinctions between dei/us-gaap share counts. This goes well beyond structured fields without contradicting 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?

Front-loads the primary use case and follows with organized bullets, but the volume of detail (sign rules, share count nuance, multiple recipes) makes it long. Most sentences carry necessary operational guidance, though there is room for trimming.

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 covers return-value nuances (raw_data.value, table sign presentation) alongside parameter and usage guidance. For a complex 8-parameter search tool, it provides everything an agent needs 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%, but the description still adds operational meaning: search operator rules (spaces=AND, commas=OR, prefer one word), a period_history recipe for de-cumulating, and fiscal_period pitfalls. This is well beyond schema text.

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 ('searches') and resource ('raw XBRL facts (~3,000 per filing, with dimensional breakdowns)'), and distinguishes from sibling get_financials by contrasting scope and speed. Examples of use cases (segment revenue, industry metrics, as-filed figures) make the purpose unambiguous.

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

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

Explicitly says when to use (numbers standard statements don't break out, as-filed figures) and when not (standard statements and the 250+ standard metrics use get_financials). Adds scenarios for concentration search, past filings, and standalone quarters with specific parameter recipes.

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, non-destructive, open-world), and the description adds real behavioral context beyond them: default 2-year window, 2013 data horizon, ~20K char response cap with narrowing advice, 8-Ks returning metadata only, and the delisted-company 410 gate that cik bypasses.

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-loads the trigger and is organized into scannable bullets, but it is long and repeats content already present in the schema parameter descriptions (delisted/cik guidance, fiscal-period indexing). A trim would help, though nothing is wasted enough to hurt usability.

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

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

With no output schema, the description correctly carries the return-shape burden: form type, dates, accession number, and per-section sizes for 10-K/10-Q/DEF 14A versus metadata-only 8-Ks. Combined with the data horizon, defaults, and cap, an agent has everything needed to call 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 coverage is 100% and schema descriptions are already detailed, but the description adds cross-parameter interaction semantics: fiscal_year overriding years, Q4 collapsing into FY, form_subtype being incompatible with fiscal_year/fiscal_period, and cik bypassing include_delisted. Some of this repeats the schema, so it lands just above the baseline rather than at 5.

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 (list a company's filings) and immediately enumerates the covered form types with plain-English glosses. It also explicitly distinguishes itself from siblings get_filing_index and compare_earnings_calls, so an agent can route 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?

Opens with an explicit 'Use this when...' trigger and follows with three concrete uses (fetch accession_number, pin a periodic filing, inventory sections/confirm existence), plus named alternatives for adjacent needs. The 8-K vs fiscal-period indexing rule is spelled out as a when/when-not condition.

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 (readOnlyHint, openWorldHint, destructiveHint=false), and the description adds substantial behavior beyond them: the exact return shape, the newest-date-then-largest-company sort that makes small `limit` values meaningful, the alias/union semantics with a cap of 50, and the polling caveat about late-extracted filings needing lookback and dedupe.

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 usage scenarios and cleanly sectioned with bold Returns/Portfolio filters headers, so an agent can skim. It is somewhat long and repeats a fair amount of what the schema already says, which keeps it short of 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?

No output schema exists, and the description fully compensates by specifying the returned fields, ordering, and the form_subtype classification. Combined with the routing guidance to get_filing_section and list_filings, an agent has everything needed to call and consume 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 description coverage is 100%, so the baseline is 3 and the heavy lifting is already done in the schema. The description largely restates that content (ticker alias, union cap 50, limit/sort, since floor) rather than adding new parameter meaning, earning no bump above baseline.

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 ('SEC filings came out recently') and gives concrete user-facing phrasings that pin down the intent. It explicitly separates itself from siblings ('For every filing of ONE company, use list_filings'), 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 (recent filings across the universe or a portfolio list, alerts, daily checks) and when-NOT (not point-in-time; single-company historical = list_filings with vantage_date; full-company listing = list_filings). It also warns against per-ticker fan-out, which directly shapes invocation strategy.

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 and destructiveHint=false, a low bar. The description adds non-obvious behavior beyond them: results are LATEST-snapshot only, an unsupported metric+period combination returns a 422 naming the supported set, tag-filtered results silently exclude unclassified companies, and responses cap near 20K chars, forcing lower limits or stricter filters.

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-loads purpose, then scoping caveats, then use cases; no sentence is filler and every example teaches a distinct filter pattern (valuation, growth, tag intersection). It runs long, but the length is driven by the genuinely large parameter surface 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?

For a 6-parameter screening tool with no output schema, the description covers invocation, valid value sources, error behavior, and tool routing well. The one gap is that it never says what a result row contains (which company fields come back), though the sibling set and schema largely imply 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?

Schema coverage is 100%, so a 3 would be the floor, but the description exceeds it: it explains where metric IDs, period types (including the growth form period_type="ttm.yoy") and sector codes live, and the examples demonstrate the nested filter array shape, operator usage, and required_tags/excluded_tags pairing that the schema only gestures at.

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

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

States a specific verb and resource with scope ('Screen 5,500+ US companies by financial metrics') and immediately distinguishes itself from the sibling signal-screening tool by naming screen_filing_signals and its domain. An agent can pick this over search_companies or get_financials 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 explicit when-to-use via five worked use cases and an explicit when-to-use-the-other-tool rule ('To screen by filing SIGNALS ... use screen_filing_signals ... then intersect with a metric screen here'). It also points to get_metric_history for the full-history case, which is a real alternative an agent would otherwise guess at.

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 give readOnlyHint/destructiveHint=false/openWorldHint, so the safety profile is covered. The description adds useful non-obvious behavior: 'Most signals are LLM-classified, not computed facts', the source corpus, and the companion_accessions workflow for IR rows. It stops short of describing pagination or return shape, but for a read-only screening tool this is above the bar.

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 organized under a Use Cases header, but the signal-id enumeration is long and largely duplicates the schema enum descriptions, and the M&A/companion paragraph could be tightened. Every sentence roughly earns its place, but the total is heavier than needed at 10 params / 100% schema coverage.

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 10-param, 3-enum, no-output-schema screening tool, the definition covers corpus, signal taxonomy, match semantics, ordering rationale (why market_cap exists), date-window behavior, and the ir_partnership companion workflow. An agent can invoke this correctly from the description alone.

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 still adds value by explaining match_mode semantics ('all' = same-row targeted screening vs 'any' = broadcast discovery), the ticker-vs-omit behavior for universe screening, and the companion_accessions follow-up on ir_partnership rows — meaning beyond the raw 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 (screen filing/call/earnings signals) and opens with concrete example queries that pin the scope. It explicitly names the sibling it is not — 'Not metric screening (P/E, ROIC: use screen_companies)' — so an agent can separate it from screen_companies 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 explicit when-to-use (red-flag/event screening across filings, earnings releases, calls), when-not (metric screening), a named alternative (screen_companies), and per-scenario examples mapping natural-language questions to parameter combinations. It also warns against looping company-by-company and directs the agent to use `ticker` only for a single-company inventory.

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 readOnly/destructive/openWorld, so the bar is lower. The description adds meaningful context: fuzzy matching handles partial names and typos, delisted companies are ranked lower and flagged [delisted], and the terminal no-match semantics for non-US symbols. Doesn't describe return ordering details or response shape, but that's minor.

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 primary use case, then bolded sections for delisted handling, not-for cases, and coverage boundaries. Slightly long, but each section earns its place given the tool's role as a routing/coverage check.

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 pivotal role as a resolver and coverage check, the description is complete: it explains what it returns, how delisted entities behave, what it's not for (with alternatives), and the terminal no-match behavior. No output schema exist, and the description compensates by enumerating returned fields.

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 non-obvious operational guidance beyond the schema: the 2-5 uppercase letters ticker heuristic, the tip to pass all-caps names in normal casing, and the foreign issuer name-vs-local-symbol rule. This compensates for the subtle pitfalls the raw schema might not convey.

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 (resolve company name/ticker to canonical ticker or CIK) and explicitly scopes the tool as a prerequisite step before other tools. Clearly distinguishes itself from search_sec_filings and screen_companies by naming them as alternatives for different use cases.

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 (need exact ticker/CIK from a name or ambiguous ticker), when-not-to-use (concept/theme/industry discovery, with named alternative tools), and a critical routing rule for delisted companies (pass returned cik downstream, except get_stock_price). Also warns that a no-match on a non-US symbol is terminal.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds value beyond them: keyword-only (non-semantic) matching with a concrete false-positive example, section-level enrichment limited to 10-K/10-Q, result dedup and recency sorting, and the NPORT-P crowding caveat. This is a genuinely honest, behavior-revealing disclosure.

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

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

Core purpose is front-loaded and the use-case list is high-value for a 9-param tool, but the form-type catalogue and limitations are verbose enough that some content duplicates schema guidance. Well-structured with headers and bullets, just slightly long.

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: filing-level results with aggregated statistics, section pointers for 10-K/10-Q, and metadata-only responses for other forms. An agent has enough to call and interpret the 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 the baseline is 3; the description adds cross-parameter semantics (query+form_type combos, what omitting form_type does, combining date_from with form_type='8-K' and rank_by='relevance'). It doesn't add syntax detail beyond the schema, which already documents operators and spellings.

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 (full-text search of SEC filings) with scope (since 2001) and explicitly distinguishes itself from siblings by naming alternatives (get_filing_index, list_filings, screen_companies, compare_earnings_calls). An agent can immediately tell what this does and what it isn't.

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 five concrete use-case examples with exact query/form_type/company combinations, and routes to alternative tools for adjacent needs (known company filings, numeric screening, earnings-call trends). It also names the conditions that select this tool over alternatives, leaving little 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety/duplication profile is covered. The description adds the key behavioral fact that text is transmitted to the MetricDuck team and clarifies the user-vs-model provenance handling, but says nothing about confirmation, rate limits, or irreversibility.

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

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

Three short sentences, front-loaded with the gating condition, followed by parameter guidance and the action. No filler, nothing redundant.

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 3-param, no-output-schema, write-side tool the definition covers when to call, what is transmitted, and how to fill both non-obvious fields. Only minor gaps remain (no mention of confirmation or return behavior), and there is no output schema requiring explanation.

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 goes slightly beyond the schema by mapping real-world conditions onto the source enum ('user when the user wrote it, model when you summarised it') and instructing that message should carry the user's words, which reduces the chance of mis-filling.

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 (send) and resource (feedback/text to the MetricDuck team), and the title/name plus 'Sends the text to the MetricDuck team' make the action unmistakable. No sibling tool does anything comparable, so there is no ambiguity to resolve.

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, hard gating: 'Call ONLY when the user asks to send feedback to MetricDuck.' This is an unambiguous when-to-use constraint with an implicit when-not (do not call otherwise), which is exactly what an agent needs for a user-triggered side-effecting action.

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