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?

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 confirm a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description goes well beyond that: it warns values are not restated, that vantage_date only bounds visible filings rather than restating figures, and that get_financials/get_metric_history flag a LOOK-AHEAD. That is genuine behavioral context an agent cannot derive 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 purpose then contents then routing, and each sentence carries routing or scope information. The final paragraph on non-point-in-time semantics is dense and long, but it is load-bearing 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?

No output schema exists, yet the description enumerates the returned sections thoroughly enough that an agent knows what to expect, and it covers freshness semantics, depth presets via the schema, and sibling boundaries. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, and the depth enum (snapshot/core/full with character budgets) is fully documented in the schema itself. The description adds only the 'latest snapshot only' framing, so the baseline 3 for a schema that does the heavy lifting is appropriate.

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

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

States a specific verb (get), resource (company overview), and scope (comprehensive, single call) then enumerates the exact data families returned: valuation, profitability, cash flow, balance sheet, capital allocation, segment/geographic mix, earnings insights and flags. It actively distinguishes itself from siblings such as get_financials, get_xbrl_facts, get_filing_index and compare_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?

Explicit routing: 'Latest snapshot only — use get_financials for multi-year trends, get_xbrl_facts for multi-period segment history, get_filing_index for a signal map...'. It also states the negative case (not point-in-time) and names the exact alternative tool family for 'as of <past date>' work, including the vantage_date parameter.

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, open-world, non-destructive access, but the description adds substantial behavioral context: figures are management's own non-GAAP-adjacent characterization, each figure may carry a deep-link and verbatim quote, absence of a receipt is not evidence of error, and point-in-time behavior is explained including how revised releases arrive as new accessions. This goes well beyond what annotations provide.

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

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

The description is front-loaded with the core identity and return contents, then moves through distinctions, use cases, caveats, and exactness. It is long but appropriately detailed for a complex tool with no output schema; however, some point-in-time detail overlaps with the schema's vantage_date description, keeping it just short of maximally concise.

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 thoroughly: it names the income statement and cash-flow fields returned, explains that figures may include deep-links and verbatim quotes, warns that the table abbreviates values, and points to `<raw_data>` for exact figures. Combined with its caveats and timing context, an agent has everything needed 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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that `quarters` walks back from `vantage_date` rather than from today, and that vantage_date bounds which releases are visible rather than which extraction is served. This is useful parameter interaction detail not fully captured 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 resource (8-K earnings-release financials), enumerates the exact headline figures and cash-flow items returned, and explicitly distinguishes itself from get_financials and get_company_overview. An agent can immediately tell what this tool produces and when it differs from siblings.

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

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

It gives explicit use cases with examples and names the alternative tools, explaining that get_financials serves audited XBRL filings while get_company_overview's earnings section is prose without figures. It also states the key timing advantage: this is often the only structured source for fresh quarter capex/OCF/FCF before the 10-Q lands.

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/openWorld/non-destructive), and the description adds substantial behavior beyond them: per-cell honesty states (present/pending/none), exact fiscal-period deck joins, ±1d webcast matching, and the caveat that a missing webcast is not 'no webcast held' when the calendar isn't harvested. It also flags non-point-in-time semantics and points to vantage_date tools for as-of queries.

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 usage, then routing. Dense but nearly every clause carries operational meaning. Slightly verbose in its emphasis-heavy formatting (CAPS, arrow notation), which is stylistic rather than wasted, keeping 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?

No output schema, so the description carries the return-shape burden—and it does, explaining that rows are per fiscal period and what each artifact cell contains and how coverage gaps are represented. Combined with the routing and point-in-time caveat, an agent has everything needed to call and interpret 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% and both parameters are documented in the schema itself (limit's range/default, ticker's format). The description adds no syntax or format detail beyond the schema, so the baseline 3 is appropriate—the schema is doing the heavy lifting.

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

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

States a specific verb+resource ('per-fiscal-period earnings DOCUMENT INDEX — one row per quarter/year') and enumerates exactly what each row holds (8-K, transcript, 10-Q/10-K, deck, webcast). It self-describes as a 'navigation index, not figures,' which separates it from data siblings without ambiguity.

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 user questions it answers and explicitly routes competing needs to named siblings: numbers→get_earnings, audited statements→get_financials, IR calendar→get_company_events, deck text→get_ir_documents, call content→compare_earnings_calls. When-to-use and when-to-use-something-else 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 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 supply readOnlyHint/openWorldHint/destructiveHint=false, but the description adds substantial behavior the annotations cannot: pagination and trunkation semantics, the omission-driven mode switch (omit section_id → outline; omit accession_number → latest filing), the delisted-ticker error path, and companion-8-K behavior. This is well past the reduced bar that annotations set.

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 trigger sentence, then clearly headed modes, use cases, and related-tool routing — structure is strong. It is nonetheless long, and the seven worked use-case examples partly restate routing already handled by the section_id catalog and the related-tools paragraph, which is mild redundancy rather than dead weight.

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-parameter, two-mode tool with no output schema, the description covers the return shape (paginated chunks; section list with previews in outline mode) and the major fallback paths. A few auxiliary switches (include_delisted, include_companions, char_offset cursoring) are documented only in the schema, which is defensible at 100% coverage but leaves the prose not fully self-contained.

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 description genuinely earns above it: it defines the section_id-vs-accession_number interplay, the outline mode triggered by omission, and when to prefer query against a table_* id. It stays a notch below 5 only because most individual parameter semantics still live in the schema text rather than the 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+resource ('Read Filing Section' returning a section's text, paginated) and enumerates the content classes it covers (risk factors, MD&A, earnings releases, transcripts, proxies). It explicitly distinguishes itself from siblings by name — `search_sec_filings`, `list_filings`, `get_ir_documents`, `compare_earnings_calls` — so the agent can route 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 triggers drawn from user phrasings, documents the two operating modes and how the argument set selects between them, and adds a routing paragraph for adjacent cases (cross-quarter trends → compare_earnings_calls; slide decks → get_ir_documents; phrase lookup → search_sec_filings). No alternatives are left to inference.

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

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

Annotations only cover readOnly/openWorld, but the description adds substantial non-obvious behavior: the markdown table is quantised/abbreviated while <raw_data> holds exact values, the ~20K char cap drops whole statements, and vantage_date does NOT reconstruct point-in-time values because restated figures carry a look-ahead warning. These are exactly the operating hazards an agent needs.

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

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

Front-loaded with purpose and defaults, then layered with caveats; every section (exactness, truncation, adjusted EBITDA) carries distinct information. It is long, and the vantage_date warning duplicates part of the schema description, but no sentence is purely 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 and five parameters, the description compensates by explaining return shape (markdown tables plus <raw_data> block, per-period filing citations with accession and filed date) and truncation behavior. Nothing an agent needs in order to call and interpret this 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 baseline would be 3; the description goes further by tying parameter values to concrete outcomes (defaults of all three statements / quarterly / 2 years) and by explaining the look-ahead semantics of vantage_date beyond the schema's own note, plus the Adjusted EBITDA caveat. It does not add syntax detail for years/period beyond 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 ('Get multi-period financial statements: income statement, balance sheet, and cash flow in one call') and explicitly distinguishes itself from get_filing_index/get_filing_section for qualitative work, setting the boundary of its scope. An agent can pick it out from the ~22 siblings immediately.

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 explicit when-to-use guidance plus four natural-language use cases that map directly onto parameter combinations (annual/years=5, statements=['balance'], vantage_date). It also names the alternative tools for qualitative analysis and for true as-originally-filed series (get_xbrl_facts with period_history=true), so both the use and the non-use case are 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 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 only declare readOnly/openWorld, so credit is due for the substantial added context: the consolidated-only storage model, the fiscal-year gap during earnings season with the appended 8-K pointer, the LOOK-AHEAD restatement warning on vantage_date, and citation behavior per accession. These are non-obvious behaviors 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 the fiscal-label caveat, and the Use Cases block aids scanning. It is dense and long for a 5-param tool, and the vantage_date paragraph duplicates schema text, but nearly every sentence carries routing or behavioral signal.

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 5-param tool with no output schema, the description covers return shape (newest-first labeled rows, citations, appended 8-K pointer), failure modes (NULL sector metrics, miss-steering catalog), and all sibling boundaries. 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 coverage is 100%, so baseline is 3; the description earns above that by adding catalog guidance for metric_id (canonical names, sector alternatives for banks/insurers, non-exhaustive miss behavior) and clarifying the custom-multiple recipe. It largely restates vantage_date semantics already present in the schema, which caps it at 4.

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

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

States a specific verb+resource (time series for one metric) and immediately scopes it: consolidated-only, newest-first, fiscal-labeled. It distinguishes itself from siblings by naming get_xbrl_facts and get_filing_section for the by-segment case and get_stock_price for single-date prices.

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 (Use Cases list with three worked examples), when-not (segment/geography/product breakdowns are excluded and routed to two named alternatives), and edge-case routing (price multiples vs. get_stock_price, custom multiples recipe). Nothing material is left to inference.

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

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

Annotations 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 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 already declare readOnlyHint/openWorldHint/destructiveHint=false, so safety is covered; the description adds substantial non-schema behavior: the exact sort tiebreak (company size within a date), why limit=15 during earnings week behaves as it does, the polling look-back/dedupe caveat for late-extracted filings, and the stated return field set. That is well beyond what annotations provide.

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

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

Front-loaded with the triggering scenario, then Returns / Portfolio filter / related-tool routing, so an agent can stop reading early. It is dense but nearly every sentence carries routing or behavior information; the bold headers add structure at the cost of some length.

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

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

With no output schema, the description compensates by naming the returned fields and ordering, defining form_subtype values, and covering the mutation-adjacent pitfalls (late extraction, dedupe). Nothing an agent needs to call this correctly appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description nevertheless adds meaning the schema only partially carries — the ticker/tickers union-with-cap-50 semantics, the alias equivalence, and the funnel from the 'since' floor plus the look-back dedupe advice. It stops short of documenting limit behavior beyond what the schema already says.

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 recent SEC filings') and anchors it with concrete user phrasings ('any new 10-Ks this week?', 'who reported earnings today?'), which removes ambiguity about scope. It explicitly distinguishes itself from list_filings (one company, all history) and get_filing_section (read a row's content).

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 triggers via sample utterances, names the alternatives for adjacent needs (list_filings for a single company, get_filing_section to drill into a filing), and states the portfolio-union semantics and 50-ticker cap so an agent knows one call covers the whole portfolio. Also flags the non-point-in-time constraint and the past-date alternative.

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.