OptimistFi

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

The description adds meaningful behavioral detail beyond the readOnlyHint annotation: it states the tool runs from precomputed stores with no live model call, and clarifies how response modes alter the output. It also discloses that when no investment case exists, the tool returns data and says so plainly rather than inventing a thesis.

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 detailed but well-organized, front-loading the core value proposition and using bullet points to structure the return content. The response-mode breakdown is concise and actionable, with no redundant filler.

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

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

For a tool with no output schema and no parameter descriptions, the description covers the return values, usage context, alternative tools, edge-case behavior, and response modes. An agent has enough information to invoke 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?

With 0% schema description coverage, the description must compensate. It thoroughly explains response_mode and its four values, and the entity is obvious from context. However, reading_level is never mentioned, leaving its meaning and effect uncovered—a clear gap given the schema provides no descriptions.

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

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

The description clearly states the tool returns the complete OptimistFi read on a company, combining valuation data, an investment thesis, and bull/bear cases. It distinguishes itself from per-topic sibling tools like get_valuation and get_thesis, making its purpose and 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?

It explicitly frames the tool as the front door for general company questions and names the per-topic alternatives (get_valuation, get_thesis, get_thesis_impact, what_changed) for when only one piece is wanted. It also explains the behavior when no investment case exists, giving clear guidance on expected outcomes.

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 readOnlyHint=true, so the description adds real behavioral context: it returns the full answer() bundle for every name, passes response_mode through without a second call, and explains how names without a built case are handled. This goes beyond what annotations alone convey, though it stops short of describing response shape in detail.

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

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

The description is dense but front-loaded with the core purpose and use case. The only minor redundancy is 'side by side' and 'weigh against each other', and the response_mode explanation could be slightly tighter, but every sentence contributes useful 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?

For a comparison tool with no output schema, the description adequately explains what the response contains (full answer() bundles), how to invoke it, what to do for single companies, and how missing cases are handled. The main omission is a semantic explanation of reading_level, but the parameter schema still provides its enum and default.

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 0%, so the description carries the burden for parameters. It clarifies 'entities' as the companies to weigh, and explains response_mode by listing its values and pass-through behavior. However, reading_level is never mentioned, leaving one of three parameters semantically unexplained despite the low schema coverage.

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

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

The description names a specific verb ('Compare'), a resource ('two or more companies'), and the output (valuation data, investment thesis, helps/hurts). It also distinguishes itself from answer() and screen by stating what kind of question it serves ('X vs Y, which is the better business / better buy / more defensive?').

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

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

Explicitly states this is the front door for side-by-side comparisons and directs single-company questions to answer(). It also clarifies that the comparison is based on investment cases rather than raw screener ratios, giving an agent clear selection criteria among siblings.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds useful behavioral context beyond that: each row is 'sourced and dated', consensus targets are distinguished from per-firm targets, and firm target rows include 'the news receipt'. This gives the agent expectations about data provenance and granularity.

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 appropriately sized for a multi-mode tool: a one-line purpose statement, a clear intro to the `kind` parameter, and a bulleted list where each bullet earns its place by describing a distinct view. There is no fluff or redundancy, and the important 'sourced and dated' note is placed at the end.

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

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

An output schema is present, so the description rightly focuses on distinguishing the five modes rather than return fields. It covers the core behavioral differences (consensus vs per-firm, contents of actions, estimates) and data provenance. Minor gaps like sorting/pagination behavior are not addressed, but the output schema and defaults reduce the need for those details.

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

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

The `kind` parameter is thoroughly documented with 20 aliases and per-value return semantics, which is essential given the schema's 0% description coverage. However, `entity` and `limit` are not described in the text; `entity` is only faintly implied by 'a stock' and `limit` is left to default conventions, so the description does not fully compensate for the schema's lack of detail on those parameters.

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

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

The description opens with a specific purpose ('What Wall Street currently thinks about a stock') and breaks out five distinct sub-views, each with concrete content summaries. This clearly distinguishes it from sibling tools like get_earnings by focusing on analyst sentiment rather than raw 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?

The description states that `kind` selects the view and gives a substantive definition for each kind (e.g., ratings = standing analyst ratings, actions = recent upgrades/downgrades). This provides enough context for an agent to choose the right mode, though it does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

Annotations only declare readOnlyHint=true, but the description adds crucial behavioral context: every record is confidence='estimated', dates are derived rather than confirmed, and each record carries its derivation basis. This is exactly the kind of caveat that prevents an agent from misinterpreting the 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?

The description is tight and well-ordered: a one-line definition, then coverage details, then a critical data-confidence caveat. Every sentence adds value, and the most important caveat is clearly emphasized.

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?

The behavior and data caveats are thoroughly described, and the presence of an output schema covers return structure. However, parameter semantics remain incomplete—particularly 'types' and 'limit'—leaving a noticeable gap for a tool with only three parameters.

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 0%, so the description should compensate, but it only indirectly mentions the entity and event categories. It does not explain the 'types' parameter values, how 'limit' applies, or what format 'entity' should take. The mention of earnings and clinical-trial readouts hints at possible types but is not sufficient for reliable query construction.

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

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

The description clearly defines the tool as a forward-looking catalyst calendar for an entity, covering projected earnings dates and clinical trial readouts sorted nearest-first. It specifies the resource and scope, though it does not explicitly contrast itself with sibling tools like get_earnings or get_event_studies.

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

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

The description implies usage for future scheduled catalysts via words like 'forward,' 'scheduled ahead,' and 'nearest first,' and it names the two covered event categories. However, it provides no explicit when-to-use/when-not-to-use guidance and does not mention alternative tools for confirmed or past events.

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

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

Beyond the readOnlyHint annotation, the description exposes key behavioral subtleties: buyback authorizations are kept distinct from actual cash spent, data is free from SEC XBRL/filings, and an empty result for a kind is 'not proof it never happened.' This materially prevents misinterpretation.

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 information-dense but efficiently organized: a one-line scope statement, a bulleted explanation of each kind, and a crucial caveat. Every sentence adds value, and nothing is redundant with the schema's enum values.

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?

The output schema and detailed `kind` semantics make the tool largely self-contained for a read-only query. The main gaps are the lack of explicit meaning for `limit`/`periods` and no guidance on sibling alternatives, which keeps it from being fully complete.

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

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

The `kind` parameter is explained exceptionally well, including aliases and the meaning of each view. However, schema description coverage is 0% and the description does not clarify `entity`, `limit`, or `periods`, so those parameters must still be inferred largely from their names and defaults.

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

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

The description opens with a specific resource and scope: 'How a company returns capital to shareholders and changes its share structure.' It then defines each `kind` view so precisely that the tool's purpose is immediately clear and distinct from likely sibling tools.

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 strong context for selecting among the tool's own `kind` values and a valuable caveat about missing data. However, it does not name sibling tools or explicitly say when to prefer this tool over alternatives such as `get_calendar` or `get_filings`.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context: output is ordered by ticker, pagination via 'after', and the scope limited to feeds without an external oracle. It does not contradict annotations, and while it omits error handling and defaults, the annotation lowers the burden.

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 'Diagnostic' and the main purpose, then covers pagination and use case. The enumeration of feed names is necessary context, though somewhat dense. It is not overly verbose, and every sentence adds information, but it could be tightened slightly without losing meaning.

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

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

For a read-only, paginated list tool with an output schema, the description covers return semantics, pagination, and use case. It does not explain defaults or detailed output format, but the output schema presumably handles that. Overall it is complete enough for an agent to call 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 0%, so the description must compensate. It explicitly explains 'after' as 'pass the last ticker as after to continue', which is essential for correct pagination. 'limit' is only implied by 'page out', but the rest of the parameter information is minimal, so the description adds significant 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?

The description clearly states a specific verb ('page out') and resource ('vendor-data confidence grid'), defines the output as one verdict per (ticker, area), and enumerates the specific feeds covered. It distinguishes the tool from sibling get_* tools by framing it as a diagnostic for internal data quality, not just a data retrieval endpoint.

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 provides clear context with an explicit use case ('Used to fill the offline sweep table's vendor columns...') and pagination instructions. However, it does not explicitly name alternative tools or say when not to use this tool, relying on the reader to infer its niche among the extensive sibling list.

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

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

Beyond the readOnlyHint annotation, the description discloses that the call fans out across many upstream sources and can take several seconds, that lists are summarised rather than dumped (with token estimates), and that since/response_mode alter the output shape. These are behavioral traits the annotation alone cannot convey.

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

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

The description is long but highly structured: purpose, contents, cost, routing guidance, and parameter semantics are each in their own block. The alternatives and parameter explanations earn their length for a complex tool; no filler or tautology.

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 aggregator with six parameters and no output schema, the description covers purpose, contents, performance, exclusions, and key parameter behavior. It omits semantics for with_market/reading_level and does not describe the response envelope, but the listed sections and response_mode guidance largely fill the gap.

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

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

With 0% schema description coverage, the description compensates for the key parameters: since is explained as converting the brief into a window and changing price reporting, and response_mode's four enum values are given concrete meanings. entity/entities are implied by the comparison use case, but with_market and reading_level receive no explanation, so compensation is incomplete.

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 line defines a specific verb and resource: a full multi-source snapshot of a company that gathers and synthesises every source. It also names sibling tools (get_thesis, get_thesis_impact, per-data-type tools) and explains the difference, so it is easily distinguished.

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 tells the agent when to reach for this tool (whole picture at once, side-by-side comparison) and when not to ('wrong tool for a narrower question'). Names alternatives for those cases and notes the heavy/slow cost, which is exactly the routing guidance an agent needs.

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, so the safety profile is covered. The description adds useful behavioral context about the data source and scoping rules, but it does not disclose return format, pagination, or how limit interacts with the results. That is a moderate gap, but the read-only annotation lowers the burden.

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 compact and well-structured, with clear section labels for HOUSE and SENATE. Every sentence adds information about how to use the tool, and the most important scoping rule (chamber) is front-loaded.

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?

The tool has 5 optional parameters and an output schema, and the description covers the main usage axes and source distinctions. It does not explain the limit parameter or what the output contains, but the output schema exists and the core selection logic is fully described. A small gap remains around limit and result ordering.

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 0%, so the description carries the full burden of explaining parameters. It explains chamber, ticker, entity, and member with usage context, but it does not explain the limit parameter or the exact relationship between entity and ticker. Still, it adds substantial meaning beyond the bare 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 clearly states the tool returns congressional stock-trade disclosures under the STOCK Act, and distinguishes the house vs senate sources. It names the specific axes (ticker/entity/member) and the data source (House Clerk's bulk export), so an agent can tell it apart from sibling tools like get_insider_trades.

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

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

The description explicitly explains when to use each parameter axis: chamber selects house or senate, house supports ticker/entity or member, senate is ticker-scoped. It also states defaults and the source of the data, giving clear context for selecting this tool over alternatives.

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

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

Annotations declare readOnlyHint=true, and the description adds valuable behavioral context: data is served from their own store with no vendor call on the request path, reported quarters are 'confirmed' vs upcoming 'estimated', and actuals for the next report are null until it reports. This goes beyond the annotation by explaining data provenance and null behavior. No contradiction.

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 sentences, dense with information, no fluff. The key output (per-quarter earnings, newest first) is front-loaded, followed by status semantics, reconciliation, and data source. Every sentence earns its place.

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?

The output schema exists, so return values are covered. The description explains the data model (confirmed vs estimated, null actuals), data source, and reconciliation. It doesn't explicitly state pagination or limit behavior, but for a read-only list tool with an output schema, this is nearly complete. Minor gap: no explicit statement about what 'entity' refers to (ticker, ID, etc.), but resolve_entity sibling likely handles that.

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 0%, so the description carries the burden. It explains the entity concept implicitly (earnings for an entity) and the limit parameter is not described. The description adds meaning about the data shape but doesn't explain what 'entity' means or how limit behaves. Baseline 3 is appropriate because the description partially compensates but leaves parameter details to 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 clearly states the tool returns per-quarter earnings data, newest first, with specific fields (reported EPS/revenue vs consensus, next report date/estimate). It distinguishes itself from get_fundamentals by noting the reported actuals reconcile with SEC filings, and the estimate is licensed analyst consensus. This is a specific verb+resource with clear scope.

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

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

The description implies when to use this tool: when you need earnings vs consensus and upcoming report dates. It mentions reconciliation with get_fundamentals, which hints at an alternative for SEC-filing-based data. However, it doesn't explicitly state when NOT to use it or name a direct sibling alternative like get_calendar for upcoming dates. Clear context but no explicit exclusions.

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?

The annotation only provides readOnlyHint, so the description adds meaningful transparency with 'Precomputed by the backtest — no model call, no vendor call' and 'not a forecast.' It discloses the nature of the data (distribution over real occurrences) without contradicting annotations. It could mention data freshness or edge cases, but the key behavioral traits are covered.

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

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

The description is dense and mostly efficient, front-loading the main concept and including useful examples of event types. Some redundancy exists between 'what HISTORICALLY FOLLOWED' and 'A what happened in situations like this record,' but overall every major idea is purposeful and the structure is readable.

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

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

For a zero-parameter, read-only tool with an output schema, the description is nearly complete: it explains what is returned, that it is historical rather than predictive, and how to use it. It could optionally mention absence of company-specific filtering or data coverage, but these are not critical given the schema and annotations.

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

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

There are zero parameters and the schema already covers them trivially, so the 0-parameter baseline of 4 applies. The description does not need to add parameter-level meaning because no parameters exist, and it appropriately focuses on output semantics instead.

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

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

The description clearly defines the tool as a historical event-studies record: for each thesis-breaking event type, it provides counts, distinct companies, and forward excess returns. It also distinguishes itself from a forecast and clarifies it is precomputed, separating it from siblings like get_recent_breaks or get_thesis_impact.

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

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

The description explicitly states when to use it: 'Use to build or answer the fundamentals event-studies view.' It also signals that it is a historical record, not a forecast, which helps avoid misuse. However, it does not explicitly name alternative tools or state when not to use it, stopping short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the description need not repeat safety. It adds meaningful behavioral context: each kind's output semantics (e.g., red_flags returns status and dated evidence, event_text returns 'the most recent filed events'), and the date-window behavior via start/end. This goes beyond the annotation without contradicting it.

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 structured as a bullet list that front-loads the core purpose and then details each kind. Every sentence adds value—no filler—and the alternatives are stated at the end. It is longer than average but justified by the many kind variants, and remains scannable.

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

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

For a tool with no output schema and many kind variants, the description covers all necessary call parameters and return semantics (e.g., status and dated evidence for red_flags). It also addresses windowing and alternatives. It doesn't detail the exact JSON shape, but that is not critical for selection; the description is complete enough for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameters. It thoroughly explains the kind enum with aliases and meanings, defines start/end as ISO date bounds, and notes that omitting them returns the most recent limit results. It does not explicitly explain entity, but that is a common identifier likely understood from context; overall, it compensates well for the missing schema descriptions.

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

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

The description states a specific purpose: retrieving a company's disclosures and coverage, with a clear enumeration of the kinds (events, press_releases, news, event_text, red_flags) and what each returns. It distinguishes itself from siblings by explicitly naming search_filings and get_filing_text as alternatives for different tasks, so an agent can tell them apart without opening schemas.

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

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

The description provides explicit when-to-use guidance by enumerating each kind and their aliases, and directly states the conditions for alternatives: 'To query across filings use search_filings; to read a specific 10-K/10-Q section use get_filing_text.' This removes ambiguity about when to pick this tool over its siblings.

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

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

Beyond the readOnlyHint annotation, it discloses bounded output, the data.truncated flag, chars_total, window_start, match_count, and how offset paging works. It also warns about the ~55,000-token cost of a full 10-K, which is valuable behavioral context.

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

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

The description is dense but every sentence earns its place: purpose, parameter semantics, output behavior, and sibling routing are all covered without fluff. It is front-loaded with the core purpose and scoping distinction.

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 7-parameter tool with 1 required parameter, an output schema, and a readOnly annotation, the description covers all operational concerns: historical selection, section guidance, keyword jumping, paging, bounded output, and the key alternative tool. Nothing critical 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 0%, so the description carries full responsibility for parameter meaning. It thoroughly explains period, section, find, offset, and output bounds, with concrete examples for fiscal year, period-end date, keyword search, and paging behavior.

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: retrieving the text of an issuer's filing for a given form, with an explicit historical vs. most-recent distinction. It also differentiates itself from get_filings by routing press-release/EX-99 content to that sibling.

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

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

It gives concrete when-to-use guidance for period, section, find, and offset, including when to prefer get_filings(kind='press_releases') for non-GAAP figures. The instruction to STRONGLY prefer a section because of token size is an explicit usage guideline.

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 say readOnlyHint=true, so the description carries the burden of behavioral disclosure and does so extensively. It explains XBRL concept provenance, that values are the most recently FILED and can be superseded by restatements, that balance-sheet metrics are point-in-time and must not be compared with duration figures, and that cached investment cases alter the response shape. This is far beyond what annotations provide.

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

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

The description is long but dense and well structured: it front-loads the core purpose, then uses parameter-name-led notes to convey exactly what each part means. Every sentence adds operational or interpretive value; there is no filler or repetition of schema defaults.

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 9-parameter tool with no schema descriptions, the description covers the core semantics and output behavior thoroughly, including response modes and cached-case behavior. It does leave some optional parameters such as start, end, and reading_level unexplained, and it does not clarify the difference between 'standard' and 'deep' response modes, but the presence of an output schema reduces the need to describe return values.

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 0%, so the description must compensate, and it does for the most important parameters: metrics lists all values and omission behavior, period explains allowed values and a subtle point-in-time caveat, periods and limit clarify row counts, and response_mode explains each mode. However, start, end, entity, and reading_level are not described, so compensation is strong but incomplete.

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

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

The description clearly states the tool returns financial statements from SEC XBRL, specifically income statement, balance sheet, and cash flow, and enumerates the available metrics. This is a specific verb and resource, and the metric list helps differentiate it from nearby siblings like get_earnings or get_filings, though it never explicitly names an alternative or states what it is 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?

The description implies when to use this tool: whenever SEC-derived fundamentals or specific financial metrics are needed. However, it gives no explicit guidance about when not to use it or which sibling tools to prefer for earnings, filings, or valuation data. The usage context is clear but not contrasted with alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description adds substantive behavioral context: it's a 45-day-stale quarterly snapshot, long-only, and explains the limitation behavior with a concrete example (Renaissance with 3,213 positions, top 200 = 56% of value). This goes well beyond the annotation, providing realistic expectations about data freshness and completeness.

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

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

The description is a series of sentences that each add distinct value: purpose, axis distinction, data characteristics, and limitation behavior. It is not overly verbose, but it is somewhat long. The front-loaded purpose and distinction make it easy to parse; a 4 reflects its efficiency without being exemplary.

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

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

With an output schema present, the description needn't detail return values, and it covers data freshness, axis context, and the partial-portfolio warning. The only gap is the undocumented 'entity' parameter, which prevents full completeness. Overall it is comprehensive but not perfect.

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

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

The schema has 0% description coverage, so the description must carry the burden. It does explain the manager parameter (fund name, ticker, or CIK) and implies the limit parameter's effect ('raise limit for more'), but the entity parameter is not mentioned at all. This partial coverage is sufficient for some parameters but leaves a key one undocumented, so a 3 is appropriate.

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

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

The description clearly states it returns the latest disclosed 13F holdings for an institutional manager, with a specific definition (fund name, ticker, or CIK) and ordering (largest positions first). It explicitly differentiates the manager-axis from get_filings(kind='events') which is issuer-axis, so an agent can distinguish it from a sibling without confusion.

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 guidance on when to use this tool vs. the sibling get_filings, and states the behavioral nuance about limited results: for partial portfolios, pct_of_portfolio won't sum to 1 and the note explains how much is shown, with a directive to raise limit for more. This is concrete, actionable guidance.

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

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

Annotations only declare readOnlyHint=true. The description adds valuable behavioral context: licensing implications ('no vendor license attaches to a derived series'), a dependency on a price provider, and the return envelope type. This goes beyond the annotations without contradicting them.

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 two concise sentences with no filler. The core purpose is front-loaded, and the licensing note is a relevant extra that earns its place. It is well-structured and easy to scan.

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

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

Despite having an output schema, the description leaves significant gaps: no guidance on how to set start/end/limit, what entity refers to, or how length affects the calculation. The dependency on a price provider is mentioned but not explained. With 6 parameters and zero schema coverage, more detail is needed for an agent 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 0%, so the description must compensate. It clarifies the 'indicator' parameter (SMA | EMA | RSI) and mentions 'underlying bars' which loosely relates to 'length', but it does not explain 'entity', 'start', 'end', 'limit', or 'length' semantics. The compensation is minimal for a 6-parameter tool.

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

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

The description clearly states the tool's action (computes technical indicator series) and its resource (prices). It names the supported indicators (SMA, EMA, RSI) and the return type ('technical_indicator' envelopes). This distinguishes it from siblings like get_prices (raw prices) and get_trading_signals (signals), even without explicit naming.

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

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

The description gives a prerequisite ('Requires a price provider') but does not explicitly state when to use this tool versus alternatives such as get_prices or get_trading_signals. The context implies it is for derived indicators, but no explicit when/when-not guidance is given.

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

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

Annotations only declare readOnlyHint=true, and the description adds substantial behavioral detail: equal issuer weights, latest stored ratios, positive multiples only, sample size/exclusion/date outputs, dividend yield unavailability, and no live fetch. It also discloses the SIC-vs-GICS distinction, which prevents misclassification.

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 compact and front-loaded with the main purpose, followed only by methodology, caveats, and parameter semantics. Each sentence contributes distinct information with no filler.

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

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

The description covers purpose, methodology, output contents, caveats, and both parameters. With an output schema present and only two optional parameters, nothing essential is missing for correct invocation.

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

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

Schema coverage is 0%, but the description fully compensates: it explains sic as a four-digit SIC code at industry level and max_price_age_days as 'seven calendar days' accepting '0–365'. This is meaningful semantic guidance beyond the schema's type/default 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?

The description opens with a specific verb and resource: 'Median valuation ratios for every SEC SIC industry, or one four-digit SIC code.' It also distinguishes itself from GICS-based classifications, making it clear this is the SIC industry-valuation tool even among siblings like get_valuation.

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

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

It states the exact scope (all SEC SIC industries or a single SIC code) and key constraints such as 'Default price freshness is seven calendar days' and 'No live market-wide fetch.' It does not explicitly name when to prefer an alternative, but the context is clear enough that an agent can infer when this tool applies.

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

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

Beyond the readOnlyHint annotation, the description adds real behavioral context: it reads the store first to avoid the ~1,000-filing submissions-index ceiling, and it explains that records include the insider name, transaction code legend (P/S/A/M/F), shares, and dollar value, and that it returns 'insider_trade' envelopes. This tells an agent exactly what to expect.

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 compact and front-loaded: the first sentence states the core purpose and scope, the second provides the sibling contrast, and the third adds behavioral detail and output shape. There is no filler, and every sentence earns its place.

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 the core invocation, the description is sufficiently complete: it identifies the required entity parameter, the per-company scope, the ordering, the behavioral advantage, and the output envelope. The only meaningful gap is the lack of guidance on optional start/end and limit parameters, which prevents a perfect score.

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

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

The schema has 0% description coverage, so the description must compensate for the parameters. It only clarifies that entity accepts a ticker/name/CIK; it does not explain the start/end date formats, the meaning of limit, or how these interact with the 'newest first' ordering. Most optional parameters remain under-specified.

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: it returns recent insider (Form 4) transactions for ONE company, identified by ticker/name/CIK, newest first. It also explicitly contrasts itself with get_insider_window, making the tool's scope instantly distinguishable from its closest sibling.

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

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

The description explicitly names get_insider_window as the market-wide complement ('who bought the most across all issuers') and positions this tool as the per-company feed. This gives clear guidance on when to use this tool versus the alternative, leaving no ambiguity about scope.

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?

The description adds substantial behavioral context beyond the readOnlyHint annotation: results are returned 'largest first,' the default txn_code 'P' means open-market purchases, and the description warns that including grants, withheld shares, and option exercises as buying is a common error. It also explains the data volume ('about 103,000 a quarter'), which signals potential cost/performance characteristics.

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 a one-sentence functional summary, then uses the remaining sentences to add differentiation, parameter semantics, and a statistically grounded warning about the default txn_code. The additional context about Form 4 composition and the 103,000-filing volume earns its place by preventing a common analytical mistake.

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?

The description provides enough orientation for an agent to select and invoke the tool for market-wide insider transaction queries, and the presence of an output schema covers return-value details. The only notable gaps are the exact format for start/end and explicit semantics for limit, but the default values and overall framing make this a mostly complete definition.

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

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

With 0% schema description coverage, the description compensates for txn_code and min_value, explicitly listing codes and stating that 'min_value bounds the dollar size.' It also refers to start/end as a 'date window,' but it does not specify the expected date format. The limit parameter is not explained in the description, leaving a gap for a tool with five parameters and no schema-level descriptions.

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

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

The description opens with a precise statement of scope: 'Every insider transaction of one type across ALL issuers in a date window, largest first.' It names the resource, the aggregation axis, the filtering by transaction type, and the sort order. It also distinguishes itself from the per-company insider feed, so an agent can differentiate it from sibling get_insider_trades.

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

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

The description explicitly frames this as 'the issuer-axis inverse of the per-company insider feed' and explains that no other endpoint serves this market-wide aggregation. It also emphasizes that the txn_code default of 'P' is central to correct usage. It stops short of explicitly saying 'use get_insider_trades when you need a single issuer,' but the guidance is clear.

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

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

Annotations only provide readOnlyHint: true; the description adds the constraint that 'context' requires entity, which is a logical prerequisite. It does not disclose other behavioral traits such as pagination, default limits, or error behavior, but the existence of an output schema reduces the need to explain return values. Overall, it contributes some context beyond the annotation but not rich behavioral detail.

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 compact, well-organized with a bulleted list, and front-loads the main statement. Every sentence contributes value—the aliases, the kinds, and the pointer to get_indicator—with no redundancy.

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 that an output schema exists, the description need not detail return values. It covers the essential usage scenarios (economic vs. context), the required entity for context, and a key alternative. It does not mention edge cases like null entity with context, but that is a minor gap given the clear guidance already present.

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?

Since schema description coverage is 0%, the description compensates by thoroughly explaining the 'kind' parameter with aliases and meanings, and clarifying the entity requirement. It does not explicitly describe 'limit' or the full semantics of 'entity', but the core distinguishing parameter is well-covered.

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 clear purpose ('macro backdrop') and elaborates with two specific kinds ('economic' and 'context'), each with concrete examples and aliases. It further distinguishes itself from get_indicator, making it easy for an agent to understand what this tool returns vs. alternatives.

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 explicitly tells the agent when to use a different tool ('For a company's own price technicals use get_indicator') and explains that the 'context' kind requires the entity parameter. However, it does not enumerate all other sibling tools or exhaustively state when NOT to use it, leaving some inference for an agent comparing with other macro-related tools.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds meaningful behavioral context: it's market-wide (not company-specific), and it details the three kinds and their aliases, clarifying what each returns (e.g., holidays, open status, IPO pipeline). It does not describe pagination or errors, but for a read-only tool with an output schema, this is adequate.

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 concise and well-structured. It opens with a one-line summary, then uses a bulleted list to explain the kinds, and ends with a sibling alternative. Every sentence serves a purpose, and the most critical information is front-loaded.

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 output schema is present and annotations cover read-only safety, the description is complete for an agent to call the tool correctly. It explains the three kinds, the optional date parameter for status, and directs to get_calendar when relevant. No critical information is missing for successful invocation.

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

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

Schema description coverage is 0%, so the description must explain parameters. It thoroughly explains the 'kind' parameter with aliases and what each selects, and mentions that 'date' optionally applies to status. The 'limit' parameter is not explained, but it is a common and self-explanatory integer. The description compensates well for the schema's lack of documentation, especially for the most important 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?

The description clearly states the tool provides market-wide reference data and enumerates three distinct kinds (calendar, status, IPO) with their meanings. It explicitly differentiates from get_calendar for company-specific data, so an agent can immediately identify scope and purpose.

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

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

The description gives explicit guidance on when to use this tool versus get_calendar: 'For one company's earnings/event calendar, use get_calendar.' It also explains what each kind returns, providing clear context for selecting the appropriate kind. No ambiguity about when to invoke it.

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 provide readOnlyHint=true. The description adds meaningful behavioral context beyond that: it is precomputed from a backtest, involves no model call, and is explicitly 'never a recommendation' but a historical record. This helps set correct expectations.

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 compact and front-loaded: it leads with the core ranking concept, then direction semantics, then usage triggers, then a caveat. Every sentence earns its place with no redundancy.

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?

The description covers purpose, direction semantics, use cases, and important behavioral caveats, and an output schema exists. The only notable gap is the unexplained limit parameter, which prevents a perfect score.

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

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

The description fully explains the direction parameter ('up' surfaces best historical forward returns, 'down' surfaces worst). However, the limit parameter is not mentioned at all, and schema description coverage is 0%, so the agent must guess what limit controls.

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 action: ranking the whole market by historical forward returns of each company's current condition set. It explicitly defines the up/down direction semantics, which clearly differentiates it from sibling tools like get_market or screen.

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

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

The description gives explicit user-query triggers: 'what looks good right now', 'what setups are strongest/weakest today', 'screen the market', and 'find high-probability situations'. However, it does not name alternative tools or state when not to use it, so it stops short of full comparative guidance.

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

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

With readOnlyHint=true already signaling a safe read, the description adds valuable behavioral context: the data is assembled from existing sources, costs no extra subscription, and every figure carries the date of its underlying input to avoid misleading date-mixing. This goes beyond the annotation without contradicting it.

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 concise and front-loaded, leading with the key headline metrics. The second sentence earns its place by explaining data provenance and the critical date-matching rationale without excessive verbosity.

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 simple one-parameter read-only tool with an output schema, the description covers the core output, data sources, cost implications, and date-stamping behavior. It is complete enough to invoke correctly, though clearer usage guidance and entity parameter semantics would make it fully robust.

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 0% for the single entity parameter, and the description does not explain how to specify the entity (ticker, name, ID) or what format is expected. The tool concept makes 'entity' inferable, but the description does not compensate for the lack of schema parameter documentation.

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

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

The description clearly identifies the resource and content: a headline overview of size and liquidity metrics (market cap, shares outstanding, average volume, short interest). It is distinct in subject matter, though it does not explicitly differentiate itself from sibling tools like get_profile or get_fundamentals.

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

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

The description implies when the tool is useful: when an agent needs headline market size and liquidity metrics, especially with properly dated inputs. However, it gives no explicit guidance on when to choose get_overview over alternatives, nor any exclusion criteria.

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 declare readOnlyHint=true, so the safety profile is already known. The description adds meaningful behavioral context: institutional holdings are sorted largest first, activist mode shows 13D stakes, and by_activist treats entity as a holder name. This goes beyond what annotations alone convey, though it does not discuss limit behavior or output details.

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 a one-sentence purpose, then organizes the view modes into a scannable list with aliases and behavioral notes. Every sentence adds value, and the closing sibling reference is useful without being verbose.

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 moderate complexity, an output schema, and readOnly annotations, the description covers all essential aspects: the three modes, alias resolution, entity semantics, sorting behavior, and the relevant sibling tool. Nothing an agent needs to correctly invoke 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 description coverage is 0%, so the description must compensate for the schema's silence. It thoroughly explains the view enum including aliases and the meaning of entity in each mode. The limit parameter is left undocumented, but the overall parameter semantics are substantially clarified beyond the bare 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 clearly states the tool's purpose: determining who owns a stock and the activist picture. It goes beyond the name by enumerating three distinct views and explicitly distinguishes itself from get_holdings, making its 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?

The description provides explicit guidance on which view to use for which question and names the sibling alternative get_holdings for a different use case. This gives an agent concrete decision criteria rather than leaving usage 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=true, and the description adds value beyond that: the emphatic 'A historical base rate, NOT a forecast' caveat and the 'context, never a promise' warning are genuine behavioral disclosures that prevent misuse. It also exposes what the return contains (n, median, 10th–90th percentile). Minor gap: it doesn't define how 'similar setup' is computed or address small-sample reliability.

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

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

Two compact paragraphs with the core purpose front-loaded and the critical forecast disclaimer separated out. Slight redundancy ('historical base rate' appears twice, and 'context, never a promise' restates the NOT-a-forecast point), but no wasted or filler sentences.

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?

The description covers what the tool computes, what it returns, how the horizon parameter behaves, and how it relates to get_thesis — and an output schema exists to carry return-format details, so those need no elaboration. The only substantive omission is entity input format, which slightly undercuts completeness for a tool with sparse schema descriptions.

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 0%, so the description must compensate. It does well for `horizon`, defining it precisely as 'the trading-day window to headline (1, 3, 5, or 10)'. However, `entity` is only implied as 'a stock' via context — its format (ticker vs. resolved name) is never stated, and the presence of a resolve_entity sibling suggests this matters. Partial compensation, with one clear gap.

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: 'Returns the forward-return distribution' for a 'stock's CURRENT chart setup' structured as a historical base rate. The framing as pattern intelligence read 'BESIDE the fundamental thesis, not instead of it' explicitly distinguishes it from fundamental-analysis siblings like get_thesis.

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 get_thesis and prescribes the pairing: 'does the chart's usual outcome agree with the fundamental case?' The 'not instead of it' language is a clear when-not boundary, and the forecast disclaimer tells the agent what the tool can and cannot be used for.

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 mark readOnlyHint=true, and the description adds meaningful context: the data is free, sourced from EDGAR, uses the filer's own wording, and represents what the issuer published rather than press coverage. It also clarifies that period can surface non-GAAP figures not present in XBRL, adding useful behavioral detail beyond the annotation.

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

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

The description is dense but purposeful, front-loading the core definition and using subsequent sentences to clarify parameters and alternatives. Some asides could be tightened, but every sentence adds relevant 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?

The description covers the tool's purpose, key parameter semantics, data origin, and alternative tools, which is sufficient for an agent to call it correctly. The missing explanations for entity and limit are minor and partially offset by the schema's defaults and obvious naming.

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

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

With 0% schema description coverage, the description compensates for the key parameters: period, with_text, and max_chars are explained with purpose and context. However, the required entity parameter and the limit parameter are not described, relying on their names and defaults for meaning.

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

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

The description clearly identifies the tool as retrieving company press releases, specifically the EX-99 exhibits attached to 8-K filings. It distinguishes these from newswire summaries and from get_filings(kind='events'), making the resource and 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?

It explicitly explains when to use with_text, what period does ('return that year's earnings releases instead of the latest'), and directs the agent to get_filings(kind='events') for the filed-event view. This provides strong, actionable routing against sibling tools.

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

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

Beyond the readOnlyHint annotation, the description discloses meaningful behavioral details: live=True makes a single uncached vendor call, other arguments are ignored, data.is_market_open indicates live vs last close, intraday bars use full timestamps while daily/longer use dates, and history depth depends on the caller's plan. It also explains license semantics per record. This is far more than annotations alone 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 each section earns its place, and the core purpose is front-loaded. The live-vs-bars distinction, interval list, and license notes are all relevant. It is dense but not redundant, though it could be tightened slightly.

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

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

For a tool with an output schema present, the description covers the main behavioral modes, interval options, license constraints, and plan-dependent behavior. The only notable omission is start/end/limit parameter semantics, which prevents a perfect score.

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 0%, so the description must compensate. It covers entity, live, and interval well, but start, end, and limit are entirely undocumented in both the schema and the description. An agent has no way to know the expected date format, range behavior, or how limit interacts with the result set. This is a significant gap for a 6-parameter tool.

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

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

The description opens with a precise action and resource: 'OHLCV bars for an entity (ticker/name/CIK), newest first.' It also clearly distinguishes bars from the live quote mode, so an agent can tell exactly what the tool returns. This fully separates it from the many sibling get_* tools.

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

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

The description explicitly says to use live=True for 'what is it trading at right now' and to leave it False for history, which is strong within-tool routing. It does not name alternative sibling tools, but the guidance is clear enough for correct selection and mode choice.

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

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

Annotations only provide readOnlyHint=true. The description adds substantial behavioral context: fields are sourced from specific filing types, the SIC scheme is intentionally labelled as coarser than GICS, and unestablished fields are surfaced in `gaps` rather than omitted. This meaningfully prepares the agent for data provenance and missing-value behavior.

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 field list and then adds purposeful context about data provenance and `gaps` handling. It is longer than minimal, but each sentence contributes operational knowledge rather than redundancy.

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

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

For a read-only tool with a single parameter and an output schema, the description covers purpose, sourcing, and missing-value behavior well. The notable gap is the complete absence of guidance on how to format or resolve the `entity` parameter, leaving correct invocation partially to guesswork.

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

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

The input schema has one required string parameter, `entity`, with no description and 0% schema coverage. The tool description never explains what `entity` should contain, such as a ticker, company name, or identifier, so it adds no value beyond the parameter name itself.

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 line identifies the tool as a company reference and enumerates concrete fields returned: description, employees, headquarters, CEO, sector, industry, and exchange. This clearly differentiates it from analytics-oriented siblings like get_company_brief or get_fundamentals, though no explicit verb such as 'returns' is used.

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

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

The description implies the tool is for static company reference data sourced from SEC filings, with caveats about SIC versus GICS. However, it never explicitly states when to prefer this tool over siblings like get_overview or get_company_brief, nor does it provide exclusion conditions.

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?

The description discloses that the data is 'Precomputed, deterministic,' which adds behavioral context beyond the readOnlyHint annotation. It also describes the structure of each break (dated call, tags, base rate), providing transparency about the output's nature. No contradiction with 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 information-dense but well-structured, starting with the core purpose, then detailing the data fields, and ending with a usage note. Each sentence adds value, and the text is not overly verbose for the amount of context it provides.

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?

The description covers the tool's purpose, data structure, and usage, and an output schema exists to document return values. The main gap is the lack of parameter explanations, but given the simplicity of the tool and the presence of an output schema, the description is reasonably complete.

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 0%, so the description was expected to explain the 'limit' and 'since' parameters. It does not mention either parameter, leaving the agent to infer their meaning from names and defaults alone. The description fails to compensate for the missing schema descriptions.

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

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

The description clearly states the resource (thesis breaks), the scope (across every tracked company), and the nature (the live 'what just broke' feed for the event-studies page). It also enumerates the returned fields, making the tool's purpose unambiguous and distinguishing it from siblings like get_event_studies.

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

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

The description gives a clear use case ('Use to show recent good/bad breaks with their odds') and frames the tool as the live feed for event studies. However, it does not explicitly mention when not to use it or compare with alternatives such as get_event_studies or what_changed, so the guidance is clear but not exhaustive.

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 declare readOnlyHint=true, which is consistent. The description adds valuable transparency beyond that: it explains the exclusion of the current partial month, the absolute nature of the count, and that every figure links to its source. It also justifies the choice of Wikipedia over Google Trends, which is useful for trust calibration.

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 concise, front-loaded with the core purpose, and every sentence adds value: the method, the rationale, the data source comparison, and the data quirks. No filler or redundancy.

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 is a simple two-parameter read operation, the description covers the essential semantics and known limitations. It does not explain the output structure, but an output schema exists (as indicated), so that gap is acceptable. Overall, sufficiently complete for an agent to call correctly.

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

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

Schema description coverage is 0%, but the description clarifies that 'entity' refers to a company and 'months' implies a time range (default 12). It does not specify exact format for entity (e.g., ticker vs name) or whether months counts trailing months, but the baseline is 3 because the description provides some compensation for the low schema coverage.

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, measurable resource ('monthly Wikipedia pageviews for its article') and frames it as a proxy for public attention, which clearly distinguishes it from financial or valuation siblings. It names alternative tools (Google Trends) but not direct siblings, yet the unique data source and purpose are unmistakable.

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 describes when this signal is useful ('alongside the investment case, where rising or falling attention can bear on a growth claim'), giving clear context for selection. It does not explicitly say when not to use it, but the reasoning is strong enough for an agent to infer appropriateness.

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 provide only readOnlyHint=true, so the description carries nearly the full behavioral burden — and it delivers: it discloses each view's output style, aliases (holding_up, check; narrative, story_check), the HOLDS_UP / MIXED / CRACKING verdict with 'receipts,' and the honest behavior when no case exists. No contradiction with readOnlyHint. Minor gap: exact response structure is not described, but content is well covered.

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 summary sentence is front-loaded and the three views are presented as clean labeled bullets, each adding genuinely useful detail. The routing sentence closes the entry. It is long, but the length is justified by three modes and zero schema coverage; nearly every sentence earns its place.

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 three-mode interpretive tool with no output schema, the description is thorough: it covers all modes, aliases, rendering options, empty-case behavior, and sibling routing. The minor gaps are unelaborated `entity` semantics and no description of the standard response format across modes, but nothing an agent needs to select and invoke it correctly is missing.

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

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

With 0% schema coverage, the description must explain the parameters and does: it defines the three `view` values including defaults and aliases, and explains the response_mode='plain' interaction with reading_level 5|10|13. `entity` is not elaborated, but its meaning is inferable from tool context. Strong compensation for the schema gap.

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 line states a specific resource and purpose: 'The investment case for a stock, and how it is holding up.' It positions itself as 'the interpretive lens for a company' that 'gives every other data point something to be measured against,' and explicitly names the sibling it is not (get_thesis_impact). With 38 sibling tools, this sharp identity makes selection 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?

The description gives clear context for when to use it ('the interpretive lens... pre-computed per company') and ends with an explicit routing rule: 'To score one specific new figure against the case, use get_thesis_impact.' It also states the empty-case behavior (says so plainly instead of inventing one). It lacks exclusionary guidance beyond the impact case, so it stops short of a 5.

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

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

Annotations only declare readOnlyHint, and the description adds substantial behavioral disclosure beyond that: it reports the full thesis first, derives a comparable-period trend, identifies the exact claim tested, explains support or challenge, states what the metric cannot prove, and guarantees no wait-and-call-again on cache miss. This is rich, honest behavior description with no contradiction.

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 information-dense, and the core promise is front-loaded: a metric interpreted against the complete investment case in one synchronous response. The later sentences earn their place by explaining cache behavior, response structure, and response_mode options. It could be tightened, but for the complexity involved it is well structured.

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?

The description covers the output flow, cache behavior, response modes, and one concrete item example, which is quite complete given the output schema already exists. The main gaps are undocumented entity semantics and reading_level values, but those are minor against the overall richness. An agent can largely understand what will happen when invoking 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 description coverage is 0%, so the description must compensate. It does add meaning for item and response_mode, explaining the earnings bundle and the plain/raw/standard/deep modes. However, the required entity parameter is not described, and reading_level is completely absent, leaving the agent to infer their meaning from context and parameter names 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?

The description clearly explains what the tool returns: a metric interpreted against the complete investment case, including whether evidence supports or challenges the thesis. It gives concrete detail such as item="earnings" bundling revenue, net income, and diluted EPS. However, it does not explicitly differentiate itself from sibling tools like get_thesis or get_analyst_view, so it loses the last point.

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

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

The description gives useful operational context, such as the tool being synchronous, complete on cache miss, and deterministic. It also explains when to use different response_mode values. However, it never states when to use this tool versus alternatives like get_thesis or get_analyst_view, so the selection guidance is only implied rather than 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 declare readOnlyHint=true, and the description adds useful behavioral details: it is 'Precomputed, deterministic' and explains the exact return structure (full counts plus per-ticker tiles with tags). This goes beyond the annotation without contradicting it, giving the agent confidence in consistency and performance.

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 moderately long but every sentence contributes: it front-loads the purpose, defines the states, outlines the return payload, and explains the strategic value. It could be trimmed slightly (e.g., the closing 'proves coverage' sentence is more persuasive than informative), but it remains focused and well-structured.

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

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

For a zero-parameter tool with an output schema, the description is exceptionally complete. It explains all possible thesis states, what tags accompany each category, and the broader rationale. The presence of an output schema reduces the need to document return values, and this description fully covers everything else an agent needs to know.

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

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

The tool has zero parameters, so there is nothing for the description to elaborate on. The baseline for zero params is 4, and the description appropriately focuses on behavior rather than parameterization. No additional parameter semantics are needed.

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

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

The description opens with a specific verb-plus-resource statement: 'every covered company's current thesis state on one wall.' It enumerates the four possible states and indicates what the tool returns. It clearly distinguishes itself from siblings by covering the whole market rather than a single entity or metric, so an agent knows exactly what this tool is for.

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

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

The description conveys that this is for a market-wide overview ('Shows the whole market at a glance') and implies it is the go-to for a high-level health check. It does not explicitly name alternative tools or specify when not to use it, but it gives enough context about its scope to make appropriate routing likely.

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; the description adds valuable behavioral context by noting the result is 'built deterministically from filed facts, precomputed — no model call.' This informs the agent that the tool is safe, fast, and non-generative. It does not contradict the annotation.

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

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

The description is dense but focused: it explains what the record is, how it is built, and when to use it. The final 'Args: entity' is redundant with the schema, but the overall structure is efficient and front-loaded.

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 does a good job conveying the content and meaning of a track record (filing dates, thesis predating the filing, deterministic construction). It does not explain optional formatting parameters, but those are secondary and carry defaults/enums.

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 0%, so the description must compensate, but it only states 'Args: entity.' It gives no added meaning for reading_level or response_mode, and even 'entity' is only loosely tied to the word 'company' in the first sentence.

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 ('OptimistFi's TRACK RECORD on a company') and a clear result: each filing crossing the thesis break condition, stamped with filing date. It is easily distinguishable from siblings that return theses or recent breaks, though it does not explicitly name an alternative tool.

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

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

The description gives explicit query triggers: 'has OptimistFi been right on X; did X's thesis break; what's the track record on X.' It does not provide exclusions or compare directly with sibling tools, so it misses the highest bar for alternative routing.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context by naming the underlying data sources (FINRA bi-monthly short interest, flow-based retail social sentiment) and explaining what each series includes. It does not contradict annotations and gives enough transparency beyond the schema.

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

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

The description is well-structured: a one-line purpose, a bulleted breakdown of the two `kind` options with aliases and sources, and a closing routing note. Every sentence earns its place, and the most important selection logic is front-loaded.

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

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

With an output schema present and the safety profile covered by readOnlyHint=true, the description provides enough context for an agent to select the correct kind and avoid nearby sibling tools. The only notable gap is the lack of explanation for `entity` and `limit`, but the purpose and data sources are otherwise sufficiently described.

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 0%, so the description must compensate. It thoroughly explains the `kind` parameter and its aliases, but it does not explain `entity` or `limit` beyond the schema's bare type/default information. The partial compensation for one parameter while leaving two undocumented keeps this at a mid score.

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

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

The description clearly states that the tool provides positioning and sentiment signals on a stock and then concretely enumerates the two kinds (short_interest and sentiment) with their aliases. It also distinguishes itself from relevant siblings by explicitly routing manager holdings to get_ownership and insider-buying screens to get_insider_window.

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 explicitly tells the agent how to select behavior via `kind`, lists all aliases, and provides direct alternatives for adjacent use cases ('For a manager's holdings use get_ownership; for the market-wide insider-buying screen use get_insider_window.'). This is exactly the kind of when-to-use guidance needed.

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

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

Beyond the readOnlyHint annotation, the description discloses significant behavioral details: ratios are built on the issuer's own filings rather than vendor data, the denominator's fiscal period is shown, negative denominators are withheld with a reason, and history mode uses each year's share count and close. This is exactly the kind of context agents need to interpret results correctly.

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 information-dense but well-structured: it opens with the exact metrics, then explains the data source and caveats, then closes with the optional history behavior. Each sentence adds value and the most important facts are front-loaded.

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

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

Given an output schema exists, the description need not explain return formatting. It covers the tool's core behavior, a critical edge case (negative denominators), the fiscal-period nuance, and the optional multi-year mode. For a read-only valuation tool with three parameters, this is complete.

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 0%, so the description carries the burden. It does explain history and periods in meaningful terms ('multi-year view', 'last `periods` fiscal year-ends'), but the required entity parameter is only indirectly referenced as 'issuer' and never explicitly defined. This is a notable gap for the one required argument.

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

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

The description names a specific set of trailing valuation ratios (P/E, EV/EBITDA, price/sales, price/cash-flow, price/book) and clearly states the tool computes them from the issuer's filed financials. It is distinct from generic 'get valuation' wording, though it does not explicitly name or differentiate from sibling tools like get_industry_valuation_medians.

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

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

The description gives good guidance for the history parameter ('Set history=True for the multi-year view') but provides no explicit when-to-use-this-tool versus alternatives, no exclusions, and no mention of related sibling tools. Selection guidance is essentially absent.

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

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

Beyond the readOnlyHint annotation, it discloses that the operation is deterministic, precomputed from filed facts, and makes no model call. It also clarifies the 'NEWLY crossed' condition and the provenance of each alert, which helps an agent trust and interpret 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?

Six short, information-dense sentences front-load the core behavior before use case, determinism, and argument formats. Every sentence earns its place and there is no filler or repetition.

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

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

For a tool with two parameters, a read-only annotation, and an output schema, the description covers inputs, omission behavior, and output semantics well. The main gap is unclear behavior when `since` is omitted or left at its schema default, since the schema marks it optional but the description implies it should be passed.

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 0%, so the description carries the full burden. It defines entities as tickers, since as an ISO timestamp, and explains that omitting entities returns a market-wide digest. This adds substantial meaning beyond the bare schema, with only minor ambiguity around schema defaults.

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 action—returns thesis-break alerts for a watchlist—and scopes results to entities whose break condition newly crossed since a timestamp. It also frames itself as the primitive behind portfolio watch/email digest, which distinguishes it from broader listing tools. No tautology or 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?

Gives concrete usage context: pass the customer's watched tickers and the last-digest timestamp, and the caller formats and delivers. It also explains the market-wide mode when entities are omitted. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it falls slightly short of full routing guidance.

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

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

On top of the readOnlyHint annotation, the description adds meaningful behavior: the output shape and the consequence of a null cik (prices/indicators work, issuer-level events do not). It also clarifies the optionality of resolution, which is behavioral context the annotation alone 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?

Three sentences, no filler, with the main action in the first sentence and the most important caveat (null cik) last. Every sentence earns its place.

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 one-parameter resolver with an output schema and readOnly annotation, this fully covers when, why, and what the result means. The null-cik caveat is exactly the kind of domain nuance an agent needs to route output appropriately.

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

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

The schema only says `query` is a required string, and schema coverage is 0%, but the description compensates by stating the accepted free-text inputs (ticker, company name, or CIK). It stops short of giving example formats or confirming that `query` is the free-text field, so it is not quite a 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?

Opens with a specific verb and resource: 'Resolve a ticker, company name, or CIK to the canonical entity {figi, cik, ticker, name}.' It also positions the tool relative to the 36 siblings by noting that every other tool takes the same free-text form, so this is the disambiguation step rather than a data-return tool.

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

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

Explicitly states calling this first is optional and gives the exact reason: confirm WHICH company a name resolved to before trusting downstream results. This tells an agent when to call it and why, without needing to inspect siblings.

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

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

Annotations only provide readOnlyHint: true, so the description carries the behavioral burden and does so richly. It discloses ranking semantics, cheapest-first sorting, `spent=True` semantics, cross-store joins, default time windows, and the coverage-note caveat about partially filled 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?

The description is long but appropriately so: 9 modes and 15 parameters require this level of detail. It is front-loaded with a one-sentence purpose, then organized into scannable bullet points, and every sentence adds operational value.

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 high complexity and the polymorphic `kind` parameter, the description covers mode selection, parameter applicability, defaults, and even the data-coverage caveat. An output schema exists, so return-value documentation is not needed, and nothing essential is missing for calling 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 0%, so the description must document parameters, and it does: kind, metric, period, ratio, min/max_value, form, item, entities, criteria, days, max_pe, spent, since, and limit are all explained with examples and defaults. This fully compensates for the empty schema.

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

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

The description opens with a specific verb+resource ('Screen the market for companies that match a condition, returned ranked') and then enumerates distinct modes via `kind`. It clearly distinguishes this from sibling get_* tools and even disambiguates internal aliases.

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

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

The description gives explicit guidance on selecting a `kind` and which arguments apply to each mode, with examples and defaults. It doesn't explicitly name sibling alternatives or say when not to use this tool, but the mode-by-mode context makes intended usage clear.

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

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

Beyond the readOnlyHint annotation, the description discloses that matching is EXACT-PHRASE and does not stem or synonymise, that it is cheap, that empty results indicate applied filters, and that each hit is a SCHEMA §2 envelope with TICKER and CIK. These are non-obvious behavioral traits an agent needs to interpret results correctly.

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 purpose, followed by parameter guidance and key caveats. It is longer than strictly necessary, but the extra sentences about exact matching, cost, and downstream chaining all add useful operational context 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?

The description covers scope, exact matching behavior, result shape, downstream chaining, empty-result semantics, and cost. With the read-only annotation and an output schema present, there is no missing category an agent needs to select and invoke 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?

With 0% schema coverage, the description compensates by explaining query as a phrase that can be double-quoted for exact match, giving forms examples like '10-K' or '8-K', and specifying that start/end are ISO dates. It does not explicitly explain the limit parameter, but the default and intuitive meaning reduce the gap.

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 line, 'Full-text search across every SEC filing since 2001 — which companies discuss something,' gives a specific verb, resource, and purpose. It clearly differentiates this from siblings like get_filings, get_filing_text, and search_trends.

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 explicitly tells the agent this returns only metadata and a URL, 'not the filing body; use get_filing_text to read one.' It also explains exact-phrase matching and shows how results chain into get_fundamentals, get_filings(kind='events'), and get_overview, giving concrete when-to-use context.

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?

The annotations declare readOnlyHint=true, but the description says the tool is STATEFUL and 'advance[s] the stored baseline to today on a successful response' — a stateful write. This is a direct contradiction with the read-only annotation, and per rubric a contradiction forces a score of 1 despite the description being otherwise transparent about the side effect.

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 a one-line purpose, then a scoped alternative, then editorial behavior, then bulleted window options. Every sentence adds information about statefulness, failure behavior, or response modes; the length is justified by the tool's complexity.

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

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

For a stateful, no-output-schema tool, the description is unusually complete: it explains window resolution sources (explicit/remembered/default), the success-only baseline advance, editorial classification output in data.editorial, and response_mode semantics. The only real gap is reading_level, which is not addressed anywhere and prevents a perfect completeness score.

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

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

The input schema has no property descriptions, so the description carries the burden. It explains since, user, neither/default, and response_mode values in detail. However, reading_level is never mentioned, and entity is only implied by 'for a company,' leaving two of five parameters without explicit semantic coverage.

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 action and resource: 'What changed for a company since a reader last looked' and 'get only what LANDED since the reader was last shown this company.' It also names the sibling it is scoped from ('This is get_company_brief scoped to a window'), so an agent can distinguish it from get_company_brief and other list tools.

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

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

Explicitly frames when to use it ('Instead of re-reading a full brief') and names the alternative tool (get_company_brief). It also gives precedence rules for since vs user and describes the default when neither is supplied, so selection logic is fully specified.

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