edgar-mcp

Overview Schema Source Related Servers Discussions Admin

compare_companies

Compare one financial figure across multiple companies and verify their fiscal periods align. Flags mismatched fiscal calendars, XBRL tags, and currencies so results are not misleading.

Instructions

Compare one financial figure across several companies, and check the dates line up.

Give it tickers or company names and one concept. It resolves each company, fetches the same concept for each, and lines the figures up side by side.

Read the warning field before you write your answer. Companies choose their own fiscal calendars. NVIDIA's fiscal 2024 ended in January 2024; Apple's ended in September 2024; Microsoft's ended in June 2024. All three are called "FY2024" and all three cover different months. When the period end dates in a comparison are more than 45 days apart, this tool sets comparable: false and a warning. Repeat that warning to the user in plain language and give the period end dates. A table of three numbers that quietly compares January to September is worse than no table.

The tool also warns when the companies matched different XBRL tags, which means the figures are defined differently even when the dates line up, and when a company reports in a currency other than US dollars.

If any company name is ambiguous, the whole comparison stops rather than guessing which filer was meant. A comparison that silently includes the wrong company looks completely normal.

Args: companies: Tickers or company names, e.g. ["NVDA", "AAPL", "MSFT"]. Two to about eight works; more is slow. concept: A concept name understood by get_financial_concept, such as "revenue" or "net_income". fiscal_year: The fiscal year to compare, e.g. 2024. Omit to use the most recent fiscal year that all the companies report. period: "annual" or "quarterly". Default "annual".

Returns: comparable, warning, fiscal_year, unit, a companies list with one row per filer (value, fy, start, end, filed, form, matched_tag, restated), an unavailable list for companies with no data, and notes.

Input Schema

TableJSON Schema

Name	Required	Default
`period`	No	annual
`concept`	Yes
`companies`	Yes
`fiscal_year`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 9, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations at all, the description carries the full burden and does so thoroughly: it explains fiscal-calendar warnings and the comparable flag, warns about XBRL tag mismatches and currency differences, and states that ambiguous companies halt the entire comparison. This is much more than the schema or annotations reveal.

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

Conciseness5/5

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

The description is longer than average but each part earns its place: the purpose is front-loaded, the warnings are essential for correct use, and the Args/Returns sections are structured and scannable. The fiscal-calendar example makes an abstract warning concrete without bloat.

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

Completeness5/5

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

Given 4 parameters, no annotations, and non-obvious warning behavior, the description covers all necessary context: parameter semantics, warnings, failure modes, and the shape of the return value. An agent has enough information to call this tool and interpret its output correctly.

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

Parameters5/5

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

Schema description coverage is 0%, but the Args section fully compensates: companies is explained as tickers/names with a count range, concept is tied to get_financial_concept, fiscal_year has an explicit omission default, and period is limited to annual/quarterly with a default. Every parameter gains meaning beyond the bare 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 opening sentence states a specific verb and object: compare one financial figure across several companies and check the dates line up. It also differentiates from the sibling tools by highlighting cross-company resolution and side-by-side alignment rather than single-filing retrieval.

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?

The description gives a clear context for use: comparing the same concept across multiple companies, and it even points to get_financial_concept for valid concept names. It does not explicitly say when not to use this tool, so it stops short of a full when-vs-alternatives statement.

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

Deploy Server