Annalist Financial Statements

Compare companies on calendar quarters

compare_companies

Read-onlyIdempotent

2 to 4 companies side by side, aligned on calendar quarters as Annalist Compare places their fiscal periods, so that companies whose fiscal years end in different months stand in the same quarter. Measures are ratio ids (corp.operating_margin, corp.roic, corp.revenue_growth, bank.roe; short names such as roic work) or statement items (revenue, net_income, total_assets, cfo). Ratios use the last 4 quarters where the ratio has them, else the quarter; a company that reports fiscal years only gives fiscal years. Each value gives the company's fiscal period, and each statement value its source document ids. Amounts stay in the currency of each company.

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": {
      "companies": "<companies>",
      "measures": "<measures>"
    },
    "name": "compare_companies"
  }
}

Input Schema

Name	Required	Description
`to`	No	last calendar quarter, in the same forms
`from`	No	first calendar quarter: CY2025 Q1, a year (2025) or an ISO date
`measures`	Yes	1 to 6 ratio ids or statement item keys, for example ["corp.operating_margin", "revenue"]
`quarters`	No	the latest calendar quarters kept (default 8)
`companies`	Yes	2 to 4 company ids from search_companies
`frequency`	No	the form of every ratio, in place of the last 4 quarters where a ratio has them; annual compares fiscal years

Output Schema

Name	Required	Description	Default
`notes`	Yes
`citation`	No
`measures`	Yes
`quarters`	Yes
`companies`	Yes
`truncated`	Yes
`conventions`	No
`quarters_matched`	Yes
`latest_common_quarter`	No

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 31, 2026

TDQS

A3.8/5.0

Behavior4/5

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

With readOnlyHint/idempotentHint already covering the safety profile, the description adds substantial behavioral context: ratio TTM-vs-quarter fallback, fiscal-year-only companies returning fiscal years, per-value fiscal period and source document ids, and preservation of each company's currency. That is real disclosure of what the output will look like, though pagination/limits beyond `quarters` aren't discussed.

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?

It is front-loaded with scope ('2 to 4 companies side by side') and every sentence carries content on alignment, measure types, fallback behavior, and output shape. The middle sentences are dense and slightly run-on, but no filler is present.

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 6-param comparison tool with an output schema, the description covers the key behavioral nuances an agent needs: quarterly alignment across fiscal years, measure identifier forms, fallback to fiscal years, and currency handling. Return-value details are appropriately left to the output schema.

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?

Schema coverage is 100%, so baseline is 3, but the description meaningfully extends `measures` semantics (ratio ids, short names like 'roic', or statement items like revenue/net_income) and clarifies that 'from'/'to'/'quarters' are calendar quarters aligned across companies' fiscal periods — details the schema descriptions only partly convey.

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

Purpose4/5

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

The opening phrase '2 to 4 companies side by side, aligned on calendar quarters' states the verb-like action, the resource, and the defining scope constraint, and the fiscal-period alignment rule distinguishes it from per-company tools like get_ratios. It never names a sibling explicitly, so differentiation is inferred rather than spelled out.

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

Usage Guidelines3/5

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

Usage is implied: comparing multiple companies on ratios/statement items. The schema notes companies come 'from search_companies', hinting at a prerequisite, but the description gives no explicit when-to-use vs get_ratios, screen_companies, or fetch, and no exclusions.

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?