get_financials

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

With no annotations provided, the description must disclose behavioral traits on its own. It does state that `as_of` yields 'figures as originally reported on that date — no look-ahead bias — for backtests', which is a key behavioral guarantee. It also notes that include_ratios derives margins, ROA/ROE, and leverage 'from the same statements.' However, it does not disclose what happens when both ticker and cik are provided, what happens if no match is found, or any rate/error behavior. The core behavioral contract (returns normalized data) is present but not exhaustive, 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 well-structured with line breaks, front-loading the core purpose in the first sentence, then elaborating on identification, as_of, and flags. It is concise for the amount of information delivered — no redundant phrases or fluff. Every sentence adds value, making it efficient for an agent to parse quickly.

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 absence of an output schema, the description should clarify what is returned; it says 'Returns the normalized data object' but does not detail the structure. It also omits edge cases like conflicting identifiers, missing data for a year, or error handling. However, for a financial data retrieval tool, it covers the essential usage aspects: identification, look-back bias prevention, and optional enrichments. The gaps are minor relative to the tool's complexity, so a 4 is justified.

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 parameter explanation. It explains ticker and cik as alternative identifiers, year is implied by 'fiscal year', as_of is described with its backtest purpose, include_provenance is explained as attaching SEC accession, filed date, and EDGAR URL, and include_ratios is described as adding margins, ROA/ROE, and leverage. Every parameter is given meaning beyond the bare schema, fully compensating for the zero 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 opens with a specific verb ('Retrieve') and a precise resource: 'normalized US-GAAP financial statements (income statement, balance sheet, cash flow) for one company and fiscal year, from SEC EDGAR XBRL.' It explicitly scopes to a single company and fiscal year, which distinguishes it from the sibling get_financials_batch. The identification via ticker OR cik is also stated, leaving no ambiguity about the tool's core function.

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 guidance on identification ('Identify the company by `ticker` OR `cik`'), explains the purpose of `as_of` for backtests with no look-ahead bias, and explains what the include flags do. It does not explicitly name alternatives or state when not to use this tool, but the single-company/fiscal-year scope implicitly contrasts with get_financials_batch. This is strong contextual guidance but lacks explicit exclusions.

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