Annalist Financial Statements

Verify a figure against the published value

verify_figure

Read-onlyIdempotent

Check a figure that a text states against the value that Annalist publishes for the item and the period: a revenue of US$114.5 billion for a quarter, a total of assets at a date, a ratio such as the operating margin for a fiscal year. The answer says whether the claim matches the published value within the tolerance (half a per cent, or half a unit of the claim's own precision), differs from it, or has no published value (a withheld value names its reason), and gives the published value with its unit, method and source document ids. The scale of the claim (thousands, millions, billions) is taken from its unit where one is given, else the scale that brings the claim nearest to the published value is used and named. Use it to check the figures of a draft, an answer or a model before they are quoted.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "company": "<company>",
      "item": "<item>",
      "period": "<period>",
      "value": "<value>"
    },
    "name": "verify_figure"
  }
}

Input Schema

Name	Required	Description
`at`	No	an ISO date: the snapshot that was the latest on that date, in place of the latest snapshot
`item`	Yes	an item key (revenue, net_income, total_assets), the label of an item (Revenue) or a ratio id or short name (corp.operating_margin, roe)
`unit`	No	the unit of the figure as stated, for example USD bn, USD millions, % or x; the scale is read from it
`value`	Yes	the figure as the text states it, for example 114.5 for US$114.5 billion
`period`	Yes	a fiscal quarter (FY2026 Q4 or Q4 FY2026), a fiscal year (FY2026 or 2026) or an ISO date of a balance sheet
`company`	Yes	company id from search_companies, for example apple or mizuho
`frequency`	No	limit the search to one frequency; ttm for a ratio over the last 4 quarters
`statement`	No	limit the search to one statement
`tolerance`	No	the relative difference allowed, as a fraction of the published value (default 0.005)

Output Schema

Name	Required	Description	Default
`item`	Yes
`name`	No
`note`	Yes
`page`	No
`as_of`	No
`period`	No
`claimed`	Yes
`company`	Yes
`verdict`	Yes
`citation`	Yes
`snapshot`	Yes
`published`	Yes
`comparison`	No

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 7, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description goes well beyond them: it defines the tolerance rule, enumerates the three possible verdicts, notes that a withheld value names its reason, and states that the published value is returned with unit, method and source document ids. It also discloses the scale-resolution heuristic used when no unit is given — a real behavioral quirk an agent would otherwise not anticipate.

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

Conciseness4/5

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

The tool's purpose is front-loaded in the first clause, and the examples and verdict taxonomy earn their space by making the tolerance semantics concrete. The sentences are long and densely punctuated, which costs some readability, but there is no filler.

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

Completeness4/5

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

For a nine-parameter verification tool with an output schema and full schema coverage, this is close to complete: it covers the verdict space, tolerance, scale handling and what is returned. The remaining gap is failure behavior — unknown company or item, ambiguous period — which the description does not address.

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

Parameters4/5

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

With 100% schema coverage the baseline is 3, and the description adds genuine meaning on top: it explains that scale is read from the unit, that otherwise the nearest-scale heuristic applies and is named in the answer, and it ties the tolerance to 'half a per cent, or half a unit of the claim's own precision', which explains the 0.005 default. It says nothing about how 'at', 'frequency' or 'statement' interact with period resolution, but those are already well documented in the schema.

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

Purpose5/5

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

The description names a specific verb and resource — checking a stated figure against the value Annalist publishes for an item and period — and grounds it in three concrete examples (revenue, total assets, operating margin). The verb 'verify/check' distinguishes it from fetch-style siblings like get_statement and get_ratios, which supply values rather than adjudicate a claim.

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

Usage Guidelines4/5

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

It states the intended use explicitly: checking the figures of a draft, an answer or a model before they are quoted. That is a clear when-to-use context, and the outcome taxonomy (matches / differs / no published value) implies when the result is inconclusive. It stops short of naming an alternative tool or an explicit when-not condition.

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

All Annalist Financial Statements tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?