TickerFacts

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

Annotations already cover the safe read-only, idempotent, non-destructive nature, and the description adds meaningful behavior beyond that: values are matched on period end, duration, and currency before grouping, and only raw observations are returned. This gives an agent a realistic sense of data provenance and processing without contradicting the annotations.

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

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

The description is dense and front-loaded: core content comes first, grouping behavior follows, and the disclaimer is kept at the end. Every sentence adds useful information, though the disclaimer is somewhat generic and could be considered boilerplate.

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 there is no output schema, the description does a good job naming the returned fields, data provenance details, grouping behavior, and what is intentionally excluded. It does not specify the exact response shape, ordering, or whether all available history is returned, but with a single ticker parameter and robust annotations it 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?

The schema fully describes the only parameter, ticker, as a 'US ticker symbol, e.g. AAPL,' so the description does not need to add much. The description reinforces the US scope but provides no extra semantic detail beyond the schema.

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

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

The description clearly states a specific resource (dated per-period cash-flow inputs) and enumerates the included metrics (operating cash flow, capex, net income, shares outstanding), so an agent can understand the tool's focus. It does not explicitly name or differentiate from sibling tools like get_fundamentals, so it loses the top score.

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 explains what the tool returns, including exclusions like 'no discount rate, no terminal assumption, no fair value and no price target,' but it never says when to prefer this tool over siblings such as get_fundamentals or get_company_research. There is no when-to-use, when-not-to-use, or alternative routing.

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

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

Beyond the read-only, idempotent, non-destructive annotations, the description discloses meaningful behavioral traits: selective coverage, whitespace normalization in quotes, and lack of automatic reconciliation of financial histories. These are exactly the kinds of caveats 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?

Three sentences, each earning its place: the first defines the core capability and return contents, the second warns about selective coverage, and the third clarifies data normalization caveats. It is dense but not bloated, and the most important 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?

For a one-parameter read-only tool with no output schema, the description is largely complete: it explains what is returned, the coverage limitations, and key interpretation caveats. A minor gap is that it does not describe the exact response structure, but the simple nature of the call and the rich caveats keep this acceptable.

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 100% coverage for the single required parameter 'ticker.' The description adds no additional parameter-level detail, but none is needed because the schema fully documents the parameter. This meets the baseline for a fully schema-documented 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 explicitly states the verb 'Read' and the resource: short, verified primary-source passages for reviewed company events. It also lists the included metadata (source URLs, section labels, dates, hashes, predecessor links), which clearly distinguishes it from sibling research or fundamentals 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 gives important usage context: coverage is selective, and absence of passages means 'unreviewed,' not 'no events.' This helps an agent avoid misinterpreting empty results. It does not explicitly name alternatives, but the context is clear enough for a single-parameter evidence-retrieval tool.

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

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

Annotations already establish readOnly=true, idempotent=true, and destructive=false. The description adds value by disclosing data provenance details (source licenses, explicit coverage dates) and by stating the data is not a live trading feed or investment signal, which helps prevent misuse. It stops short of describing return shape or pagination, but for a safe read-only tool this is reasonable.

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

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

The description is a single front-loaded sentence listing the main content categories, followed by brief caveats. It is economical and contains no filler, though the comma-separated list is somewhat dense.

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 single-parameter read-only tool with strong annotations, the description covers the data scope, provenance, freshness caveat, and intended use. There is no output schema, but the description's content list gives an agent a reasonable expectation of what will be returned. It could be more complete if it named sibling alternatives, but that gap is captured in usage guidelines.

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 already fully describes the only parameter, 'ticker', including a US ticker example. The description does not add parameter-specific semantics, but with 100% schema coverage the baseline of 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 names a specific resource and enumerates concrete content categories: company filings, quarterly insider transaction disclosures, aliases, headquarters, legal-entity relationships, source licenses, and coverage dates. It does not explicitly contrast itself with sibling tools like get_company_evidence, so it is clear but not fully differentiated.

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 contextual boundaries: it is not a live trading feed and is intended for research/education only, not as financial advice or an investment signal. However, it gives no explicit guidance on when to choose this tool over nearby alternatives such as get_company_evidence or get_fundamentals.

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 the tool read-only and idempotent, and the description adds valuable behavioral caveats: published 90% margins of error, missing/suppressed values are not zero, resident vs. workplace populations must not be combined, and the data is place-level rather than company-level. 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 front-loaded with the data inventory, followed by important caveats. Each sentence contributes useful information, though the set of disclaimers makes it slightly denser than strictly necessary.

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

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

With no output schema, the description compensates by enumerating data sources, variables, margins of error, national reference rows, and caveats. It does not specify the exact response shape, but for a single-parameter read-only lookup it is nearly 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 coverage is 100% and the schema already documents the FIPS code/name format, examples, and ambiguous-name candidate-list behavior. The description mentions lookup by FIPS/name but adds no parameter-level meaning beyond the schema, so it stays at the baseline.

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

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

The description is highly specific: it names exact datasets (Census ACS, BLS QCEW), the variables covered, the geographic scope (one US county), and the lookup key format. It also distinguishes itself from company-level tools by explicitly stating it describes a place, not company exposure.

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 use context: county-level research/education, and explicit when-not guidance: do not combine resident and workplace populations, and do not use this for company operating or revenue exposure. It stops short of a 5 because it does not name sibling alternatives such as get_economic_context or get_company_research.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by clarifying the time window (last year by default) and the behavior of unknown series ids (returns list of ids), which is useful context beyond annotations. However, it doesn't disclose potential rate limits or data freshness specifics, but the annotations carry the main safety burden, so a 3 is appropriate.

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 sentences with no fluff. The first sentence front-loads what the tool returns and the data frequency, while the second clarifies the default time range and the usage restriction. Every clause earns its place, and it is appropriately sized for 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?

Given the tool's relatively simple interface (two optional parameters, no output schema), the description is complete enough for an agent to call it correctly. It covers the main behavior (time range default), the parameter semantics (implied), and the data content. It lacks explicit handling of edge cases like invalid since formats, but that is minor for a read-only, idempotent tool. A 4 is justified because it does more than the bare minimum but isn't exhaustive.

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

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

Schema coverage is 100%, so the schema already documents both parameters (since and series) with formats and defaults. The description adds some context (e.g., default time window, comma-separated ids) but does not significantly enhance beyond the schema. It could have explained the series id format or examples, but the baseline of 3 is correct since the schema does the heavy lifting.

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

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

The description explicitly states the tool returns selected government Treasury yields and BLS series, with clear scope (daily vs monthly) and data types. It distinguishes itself from siblings like get_county_context by naming the data sources (Treasury, BLS) and the research/education purpose, so an agent can identify it as the macroeconomic data 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 implies when to use it: when Treasury or BLS data is needed, and explicitly notes the 'research and education only' constraint, which guides appropriate use. It does not explicitly name alternative tools, but the sibling list and the specificity of the data make the intended use clear. No exclusion guidance is given for when not to use it, but the context is strong.

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

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

Annotations already declare readOnly, idempotent, non-destructive safety, so the description earns credit for adding substantive behavioral context: TTM and latest_interim inclusion rules, the reporting flag, ratio computation and non-comparability notes, coverage gaps, and dataset SHA-256 / research links. It does disclose limitations (empty history = unavailable not zero; current-CIK history not reconciled across reorganizations) and even includes a compliance disclaimer.

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 and dense, packing many clauses into essentially two sentences; it is front-loaded with scope but the mid-section on quarterly derivation and reporting flags is hard to parse. It is informative but not optimally structured for quick scanning.

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 5 parameters at 100% schema coverage, no output schema, and rich annotations, the description covers the critical behavioral nuances (TTM, latest_interim, derivations, non-comparability, coverage gaps). It omits return-shape details, but with no output schema that is a minor gap for a read-only data 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 100%, so baseline is 3, but the description adds real meaning beyond the schema: it explains what 'quarterly' returns (newest 8 fiscal quarters unless quarters is given) and how quarter figures may be reported or derived as the difference of two year-to-date figures, and it explains ratio behavior (a ratio brings its inputs). It does not re-explain the metrics/periods parameters, which the schema covers.

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

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

States a precise verb+resource: SEC-derived annual observations for a US public company, retrieved by ticker. It explicitly names the sibling search_companies as the path for name lookup, and distinguishes itself from get_fundamentals_batch (single company vs batch) by implication of the ticker argument.

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

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

Provides clear conditional guidance: use search_companies to find a ticker by name, and pass quarters or period 'quarterly' for single fiscal quarters. However it never states when to prefer get_fundamentals_batch over this tool, nor when a caller would not want the trailing-twelve-month or latest_interim additions.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world behavior, so the bar is lower. The description still adds real value by disclosing that unknown tickers yield per-entry errors rather than failing the batch, that each result preserves requested/canonical identity and source lineage, and that point-in-time filtering is unsupported.

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 dense sentences that lead with the core capability and batch limit before the defaults and caveats. Every clause carries information; no filler or repetition of the title.

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

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

With no output schema and five parameters, the description does well by covering batch limits, defaults, per-entry error handling, identity/lineage, and the PIT-filtering gap. Only the response shape remains unspecified, which is a minor omission given the params and error semantics are addressed.

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

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

Schema description coverage is 100%, so the schema already documents periods, quarters, metrics and the annual/quarterly enum in detail. The description only reinforces the ticker count and default period behavior, adding no syntax or format detail beyond what the schema already provides.

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

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

States a specific verb (read), resource (annual fundamentals) and scope (1 to 20 comma-separated tickers in one request), and clarifies the batch nature that separates it from the singular get_fundamentals sibling. It never names that sibling explicitly, so the differentiation is inferred rather than stated.

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?

Communicates defaults (one newest period per issuer, all metrics when omitted) and a hard limitation ('No historical point-in-time filtering'), which helps an agent know when this tool is appropriate. It gives no explicit when-to-use vs get_fundamentals routing, so usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful context about data provenance ('Data traces to SEC EDGAR filings') and a usage disclaimer, plus the behavioral fact that results are ranked and limited. It does not disclose potential data freshness caveats or how 'latest annual period' is determined beyond the include_stale parameter.

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 states the core screening purpose in the first sentence, summarizes the return shape in the second, and adds provenance/disclaimer in the third. 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?

For a tool with 22 parameters and no output schema, the description gives only a minimal return summary ('ranked list of companies with their key figures'). It does not explain what 'key figures' are, how ranking works, or how pagination interacts with the result set. The schema covers parameters, but the description leaves some operational context unstated.

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

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

Schema description coverage is 100%, so the schema fully documents all 22 parameters. The description does not add parameter-level meaning beyond what the schema provides, which is acceptable but not additive. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Find') and resource ('US public companies') and clearly states the screening criteria (fundamentals filters, sector, profitable-only, sorted/limited). It does not explicitly contrast itself with sibling tools like search_companies, so it lacks the sibling differentiation needed for a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as search_companies or get_fundamentals. The description implies a screening use case but provides no exclusions, prerequisites, or alternative routing. The disclaimer about research/education is a restriction, not usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds non-obvious behaviors: typo forgiveness, best-match-first ordering, inclusion of former ticker-directory companies (listing_status former), and the specific output fields. This goes beyond the structured data and helps the agent predict 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?

Three sentences with no filler: the first states the core function and output fields, the second clarifies inclusion of delisted companies, and the third gives the usage routing. Information is front-loaded and every sentence adds 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?

For a 2-parameter lookup tool with no output schema, the description lists every returned field (ticker, CIK, name, exchange, sector/industry, latest annual period end), explains inclusion policy, and states the ordering behavior. This is sufficient for an agent to call it correctly and understand the result.

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

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

Schema coverage is 100% with parameter descriptions containing examples (e.g., 'apple, berkshire, or msft') and the limit constraints. The description does not add further parameter-level meaning beyond the schema, so it meets the high-coverage baseline of 3.

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

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

The description states a specific verb-resource pair: 'Find US public companies by name or ticker', details the returned fields, and explicitly positions the tool as the ticker resolver for other tools ('Use it to turn a company name into the ticker the other tools take'). This clearly distinguishes it from the sibling get_* and screen_companies 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 gives an explicit when-to-use signal: use it to convert a company name into a ticker for downstream tools. It does not name alternative tools or provide when-not-to-use guidance, but for a focused lookup tool this is a clear and sufficient 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?

Beyond the annotations, the description discloses real behavioral facts: reports are read by maintainers, there is no reply channel unless a contact is provided, and nothing is published. It also notes that free-text fields are bounded. This gives the agent an accurate model of the side effects and privacy guarantees, and does not contradict the annotations.

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

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

Every sentence earns its place: the first states purpose, the second gives call triggers, the third adds a session-completion case, and the final two cover consequences and privacy. It is front-loaded with the core reporting verb and remains compact despite covering many operational details.

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

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

For an 11-parameter tool with no output schema, the description is complete: it explains what to report, when to report, what content to include, what happens to the report, and whether follow-up is possible. The schema handles the rest, so no critical operational context is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description paraphrases schema-level guidance already present in fields like use_case ('say what the user was trying to accomplish') and would_solve_it ('exactly which fields, periods, companies or filters would have solved it'), but it does not add significant new parameter-level meaning beyond what the schema already supplies.

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: 'Report what you needed from TickerFacts and did not get, what looked wrong, what was confusing, or what worked.' It clearly distinguishes this tool from all data-retrieval siblings by establishing it as the feedback/issue-reporting channel, not a lookup or screening 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 call conditions: 'Call this whenever a tool call fails or a result lacks a figure, period, company or filter your user's task needed.' It also adds a positive trigger: 'call it once at the end of a session that went well.' This is strong when-to-use guidance, with no meaningful alternatives among the sibling tools.

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