get_financials

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

With no annotations, the description carries the full transparency burden and exceeds it: it discloses the source, the exact return shape, that most entities return empty financials with a note (with a concrete measured sample and even a Barclays example), that balance-sheet fields are well-populated while turnover/profit are sparse, and that absent filings must not be conflated with filed zeros. This is unusually rich operational 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 longer than average, but every sentence earns its place: purpose, use-case, return shape, normal-empty caveat, measured evidence, field-skew warning, and note-reading instruction. It is front-loaded with the core function and flows logically from purpose to usage to interpretation, with 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?

There is no output schema, but the description compensates by stating the return structure, enumerating the reported financial fields, explaining the empty-financials behavior, and clarifying the meaning of the note field. For a tool whose main risk is misinterpreting missing data, this is a complete and robust description.

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 already describes id as 'Entity id (a UK company)' at 100% coverage, so this dimension starts at baseline 3. The description adds meaningful provenance ('Get the id from search_entities') and reinforces that the id must be a UK company entity id, going slightly beyond the schema without needing more detail.

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: 'Filed financial figures for a UK company by entity id' using Companies House iXBRL accounts, and enumerates the exact metrics (turnover, profit/loss, net assets, cash, shareholder funds, fixed/current assets, employee count). This clearly distinguishes get_financials from sibling tools such as get_dossier or get_company_details, which serve broader company-profile purposes.

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 an explicit 'use this for' clause ('what are X's revenue / profit / net assets / how many employees') and points to search_entities as the source for the id. It does not explicitly name alternative tools for other data types or state a 'when not to use' condition, but the coverage warning strongly informs expectation-setting around use.

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