Valuein — SEC EDGAR Fundamentals & Smart-Money Data

Compare Financial Periods

compare_periods

Read-onlyIdempotent

Compare a company's core financial metrics across two fiscal periods side-by-side. Shows absolute and percentage changes with significance classification (minor < 5%, notable 5–15%, significant > 15%). The response includes a material_changes count: this is the number of metrics whose significance ∈ {notable, significant} (i.e. absolute percentage change > 5%). Use it as a quick scalar to triage filings — anything > ~3 typically signals a material event worth deeper review. Use period format: 'FY2024' for annual, 'Q1-2024' for quarterly. Pass period_a as the EARLIER period and period_b as the LATER one — if you invert them the server auto-swaps and sets swapped: true in the response so deltas always carry the correct sign (rather than silently flipping). Point-in-time safe via as_of_date. Available on all plans.

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": {
      "ticker": "<ticker>",
      "period_a": "<period_a>",
      "period_b": "<period_b>"
    },
    "name": "compare_periods"
  }
}

Input Schema

Name	Required	Description
`ticker`	Yes	Stock ticker symbol, e.g. AAPL, MSFT, BRK.B — or a CIK (SEC identifier), e.g. '0000320193'.
`period_a`	Yes	Earlier fiscal period. Format: 'FY2023' for annual or 'Q1-2023' for quarterly.
`period_b`	Yes	Later fiscal period. Format: 'FY2024' for annual or 'Q1-2024' for quarterly.
`as_of_date`	No	Point-in-time date (YYYY-MM-DD). Only returns facts with accepted_at on or before this date — eliminates look-ahead bias for backtesting.

Output Schema

Name	Required	Description
`_meta`	Yes	Response metadata (provenance, point-in-time flag, freshness, request id and warnings). Every field is documented once in the agent contract (agent_contract.meta in the server's manifest.json).
`ticker`	Yes
`changes`	Yes	Per-metric deltas: metric, label, period_a, period_b, delta, delta_pct, significance
`swapped`	Yes	True when inputs were reordered so period_b is the more recent period
`period_a`	Yes	Earlier period descriptor: label, fiscal_year, fiscal_period, period_end, filing_date
`period_b`	Yes	Later period descriptor, same shape as period_a
`as_of_date`	No
`company_name`	No
`total_metrics`	Yes	Count of metrics compared across the two periods
`material_changes`	Yes	Count of metrics flagged as a material change

Schema Changelog

Changes observed during successful MCP inspections.

Changed24 schema fields changedNov 12, 2026

addedInput schema / additionalProperties
```
Added value: +false
```
changedOutput schema / properties / _meta / additionalProperties
```
Previous value: -falseNew value: +{}
```

changedOutput schema / properties / _meta / description

Previous value: -"Provenance envelope — data lineage for every MCP response"New value: +"Response metadata (provenance, point-in-time flag, freshness, request id and warnings). Every field is documented once in the agent contract (agent_contract.meta in the server's manifest.json)."

removedOutput schema / properties / _meta / properties / as_of_date

Removed value: -{
-  "type": [
-    "string",
-    "null"
-  ]
-}

removedOutput schema / properties / _meta / properties / cost_usd

Removed value: -{
-  "additionalProperties": false,
-  "description": "Per-call cost transparency. Omitted for subscription-only and free tools, which have no MPP price.",
-  "properties": {
-    "amount_usd": {
-      "minimum": 0,
-      "type": "number"
-    },
-    "basis": {
-      "description": "mpp_charge = real pay-per-call charge (a card or MPP payment through agent-pay). mpp_rate_card = indicative price, not billed.",
-      "enum": [
-        "mpp_charge",
-        "mpp_rate_card"
-      ],
-      "type": "string"
-    },
-    "billed": {
-      "description": "true = this amount was actually charged via MPP for this call. false = indicative MPP-equivalent value only: no charge was made for this call (it was within your plan).",
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "amount_usd",
-    "billed",
-    "basis"
-  ],
-  "type": "object"
-}

removedOutput schema / properties / _meta / properties / data_plan

Removed value: -{
-  "description": "Access plan: sample | sp500 | pro | full",
-  "type": "string"
-}

removedOutput schema / properties / _meta / properties / data_quality

Removed value: -{
-  "additionalProperties": false,
-  "description": "Server-side invariants run on this response",
-  "properties": {
-    "notes": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "validation_failed": {
-      "items": {
-        "additionalProperties": false,
-        "properties": {
-          "detail": {
-            "type": "string"
-          },
-          "rule": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "rule",
-          "detail"
-        ],
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "validation_passed": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    }
-  },
-  "required": [
-    "validation_passed",
-    "validation_failed",
-    "notes"
-  ],
-  "type": "object"
-}

removedOutput schema / properties / _meta / properties / fundamentals_as_of

Removed value: -{
-  "description": "ISO timestamp when the FINANCIAL STATEMENTS were last rebuilt in bulk. Use THIS — not `last_updated` — when telling a user how current the cross-sectional fundamentals are. The snapshot is republished on every weekday price refresh while the statements are carried forward unchanged, so `last_updated` can be far more recent than the numbers it sits next to. It is a floor for a single filer, not a ceiling: a filer with a live partition receives its filing, facts and ratios intraday (minutes after EDGAR dissemination), so an entity-scoped read may carry a filing newer than this; cross-sectional ranks (factor scores, earnings signals) refresh with the weekly bulk export.",
-  "type": "string"
-}

removedOutput schema / properties / _meta / properties / last_updated

Removed value: -{
-  "description": "ISO timestamp when the snapshot was exported",
-  "type": "string"
-}

removedOutput schema / properties / _meta / properties / latency_ms

Removed value: -{
-  "description": "Wall-clock milliseconds this tool call took, measured server-side around the handler.",
-  "maximum": 9007199254740991,
-  "minimum": 0,
-  "type": "integer"
-}

removedOutput schema / properties / _meta / properties / limit_warnings

Removed value: -{
-  "description": "Soft-warning array for partial fulfillment. Each entry carries a stable subcode + remediation.options[]. AI agents pattern-match on subcode.",
-  "items": {
-    "additionalProperties": {},
-    "properties": {
-      "code": {
-        "const": "LIMIT_EXCEEDED",
-        "type": "string"
-      },
-      "current_plan": {
-        "type": "string"
-      },
-      "extensions": {
-        "additionalProperties": {},
-        "propertyNames": {
-          "type": "string"
-        },
-        "type": "object"
-      },
-      "limit_type": {
-        "type": "string"
-      },
-      "limit_value": {},
-      "remediation": {
-        "additionalProperties": {},
-        "properties": {
-          "contact_sales": {
-            "type": "string"
-          },
-          "default_action": {
-            "type": "string"
-          },
-          "options": {
-            "items": {
-              "additionalProperties": {},
-              "propertyNames": {
-                "type": "string"
-              },
-              "type": "object"
-            },
-            "type": "array"
-          },
-          "pricing_page": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "options",
-          "default_action",
-          "pricing_page",
-          "contact_sales"
-        ],
-        "type": "object"
-      },
-      "requested_value": {},
-      "returned_value": {},
-      "subcode": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "code",
-      "subcode",
-      "limit_type",
-      "current_plan",
-      "remediation"
-    ],
-    "type": "object"
-  },
-  "type": "array"
-}

removedOutput schema / properties / _meta / properties / mpp_offer

Removed value: -{
-  "additionalProperties": {},
-  "description": "Present when figures still need payment: the MPP option (price, resource_url, request body) for the full run.",
-  "propertyNames": {
-    "type": "string"
-  },
-  "type": "object"
-}

removedOutput schema / properties / _meta / properties / mpp_override

Removed value: -{
-  "additionalProperties": false,
-  "description": "Set when this single response was paid for over MPP (card, agent-pay): the payment's order was honoured for this call only. agent-pay captures the payment only when this is present.",
-  "properties": {
-    "amount_cents": {
-      "type": "number"
-    },
-    "category": {
-      "type": "string"
-    },
-    "companies": {
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "company_count": {
-      "type": "number"
-    },
-    "order_id": {
-      "type": "string"
-    },
-    "run": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "run_token_hash": {
-      "type": "string"
-    },
-    "scope_hash": {
-      "type": "string"
-    },
-    "tool": {
-      "type": "string"
-    },
-    "unlock_level": {
-      "enum": [
-        "pro",
-        "full"
-      ],
-      "type": "string"
-    }
-  },
-  "required": [
-    "order_id",
-    "tool",
-    "category",
-    "amount_cents",
-    "company_count",
-    "scope_hash",
-    "run_token_hash",
-    "unlock_level",
-    "companies",
-    "run"
-  ],
-  "type": "object"
-}

removedOutput schema / properties / _meta / properties / mpp_verification

Removed value: -{
-  "additionalProperties": false,
-  "description": "Verification tools only, when some figures are outside the caller's plan. Figures the plan covers are always verified free; a Valuein account also verifies its first figures free, once, figures outside its plan included (the verification trial, size in pricing://current). served_free = own-plan figures plus trial figures; trial_used / trial_remaining = this run's draw and what the account has left; needs_payment = figures still to pay for (the paid verification run). A guest has no trial: note says how to get it.",
-  "properties": {
-    "figures": {
-      "type": "number"
-    },
-    "needs_payment": {
-      "type": "number"
-    },
-    "note": {
-      "type": "string"
-    },
-    "served_free": {
-      "type": "number"
-    },
-    "trial_remaining": {
-      "type": "number"
-    },
-    "trial_used": {
-      "type": "number"
-    }
-  },
-  "required": [
-    "figures",
-    "served_free",
-    "trial_used",
-    "needs_payment"
-  ],
-  "type": "object"
-}

removedOutput schema / properties / _meta / properties / pit_safe

Removed value: -{
-  "description": "true iff a zero-look-ahead point-in-time cut was applied to every returned figure",
-  "type": "boolean"
-}

removedOutput schema / properties / _meta / properties / rate_limit

Removed value: -{
-  "additionalProperties": false,
-  "description": "Caller's remaining budget",
-  "properties": {
-    "limit": {
-      "maximum": 9007199254740991,
-      "minimum": -9007199254740991,
-      "type": "integer"
-    },
-    "remaining": {
-      "maximum": 9007199254740991,
-      "minimum": -9007199254740991,
-      "type": "integer"
-    },
-    "reset_at": {
-      "description": "ISO 8601 timestamp when the window resets",
-      "type": "string"
-    },
-    "window": {
-      "enum": [
-        "minute",
-        "hour"
-      ],
-      "type": "string"
-    }
-  },
-  "required": [
-    "limit",
-    "remaining",
-    "reset_at",
-    "window"
-  ],
-  "type": "object"
-}

removedOutput schema / properties / _meta / properties / request_id

Removed value: -{
-  "description": "Per-request correlation id (8-char)",
-  "type": "string"
-}

removedOutput schema / properties / _meta / properties / result_count

Removed value: -{
-  "maximum": 9007199254740991,
-  "minimum": -9007199254740991,
-  "type": "integer"
-}

removedOutput schema / properties / _meta / properties / schema_version

Removed value: -{
-  "description": "Parquet schema version from manifest.json",
-  "type": "string"
-}

removedOutput schema / properties / _meta / properties / snapshot

Removed value: -{
-  "description": "Snapshot directory name (e.g. snapshot_20260420)",
-  "type": "string"
-}

removedOutput schema / properties / _meta / properties / source

Removed value: -{
-  "const": "SEC EDGAR",
-  "type": "string"
-}

removedOutput schema / properties / _meta / properties / ticker
```
Removed value: -{
-  "type": "string"
-}
```

removedOutput schema / properties / _meta / properties / truncation

Removed value: -{
-  "additionalProperties": false,
-  "description": "Set when fewer rows were returned than requested — explains why and points to a remedy",
-  "properties": {
-    "current_plan": {
-      "type": "string"
-    },
-    "plan_limit": {
-      "maximum": 9007199254740991,
-      "minimum": 0,
-      "type": "integer"
-    },
-    "reason": {
-      "enum": [
-        "PLAN_LIMIT",
-        "DATA_NOT_AVAILABLE",
-        "FISCAL_YEAR_BOUNDARY_FILTER",
-        "OTHER"
-      ],
-      "type": "string"
-    },
-    "requested": {
-      "maximum": 9007199254740991,
-      "minimum": 0,
-      "type": "integer"
-    },
-    "returned": {
-      "maximum": 9007199254740991,
-      "minimum": 0,
-      "type": "integer"
-    },
-    "upgrade_required_for": {
-      "type": "string"
-    },
-    "upgrade_url": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "requested",
-    "returned",
-    "reason"
-  ],
-  "type": "object"
-}

removedOutput schema / properties / _meta / required

Removed value: -[
-  "data_plan",
-  "schema_version",
-  "snapshot",
-  "last_updated",
-  "source",
-  "pit_safe"
-]

Changed1 schema field changedNov 11, 2026

removedOutput schema / properties / _meta / properties / price_as_of

Removed value: -{
-  "description": "ISO timestamp when the price surfaces were last refreshed.",
-  "type": "string"
-}

First observedNov 9, 2026

TDQS

A4.3/5.0

Behavior5/5

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

With annotations already covering readOnly, idempotent, non-destructive and closed-world behavior, the description adds substantial unannotated behavior: it defines the significance thresholds (5%/15%), precisely specifies what material_changes counts, discloses the automatic period swap with a swapped:true flag rather than silent sign flipping, and notes point-in-time safety and plan availability. That is exactly the kind of context annotations cannot carry.

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 definition is front-loaded with purpose and output semantics, then moves to the triage heuristic, then parameter rules; each sentence carries information. It is somewhat dense and repeats period formatting already stated in the schema, which is a minor inefficiency.

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?

An output schema exists, so return values need not be exhaustively documented, yet the description still explains the two non-obvious response fields (significance classification and material_changes) and the swapped flag. Combined with parameter formats and point-in-time guarantees, an agent has everything needed to invoke this correctly.

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 the baseline is 3, but the description adds real meaning beyond the schema: it spells out the accepted period formats and, more importantly, the ordering contract for period_a and period_b and what happens when they are inverted. The as_of_date rationale is partly duplicated from the schema, which keeps this from a 5.

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 description names a specific verb and scope: comparing a company's core financial metrics across two fiscal periods side-by-side, including what the output contains (absolute and percentage changes plus significance classification). That is far more concrete than the tautological title, but it never names a sibling tool or states how it differs from near-neighbors like get_financial_ratios or get_company_fundamentals, so it stops short of full sibling differentiation.

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 supplies clear operational context: use the material_changes scalar to triage filings, with >3 suggesting a material event worth deeper review, and it explains required period syntax for annual versus quarterly comparisons. What is missing is explicit routing advice — no statement of when to prefer a different tool over this one.

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

All Valuein — SEC EDGAR Fundamentals & Smart-Money Data 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.