Skip to main content
Glama

Tanod

by dev.tanod
OverviewDiscussionsAdmin

utilpeek: SEC EDGAR financial statements by period (revenue, income, balance sheet, cash flow)

sec_financials
Read-onlyIdempotent

utilpeek: Get a US company's reported financials per fiscal year or quarter from SEC EDGAR. For the registrant and filings use sec_company_lookup. Returns a US SEC registrant's reported financials by ticker or CIK, annual or quarterly (up to 20): revenue, income, EPS, balance sheet, cash flow, capex and shares with us-gaap tag and filing; missing metrics are null. Latest comparable filed fact wins (/A, accession, tag ties); newer excluded concepts/start dates warn in selection. Informational only, not investment advice. Data: SEC EDGAR (public domain), cached up to 6 hours; no SEC endorsement implied. Send exactly one of ticker or cik; bad input is a 422 and an unknown company or no US-GAAP data a 404 (neither charged); an upstream outage is a 503 (not charged). Typically 1-4 s (cached under 0.1 s). Price: USD 0.005. Free: 10 utilpeek calls per IP per UTC day. Docs: https://tanod.dev/learn/sec-financials-api.html

Input Schema

NameRequiredDescriptionDefault
cikNoSEC Central Index Key, 1-10 digits, as a number or a string (leading zeros and a CIK prefix allowed, such as 320193 or 0000320193). Send ticker or cik.
limitNoNewest periods to return, 1-20 (default 4).
periodNoannual: fiscal years from 10-K filings; quarterly: the discrete quarters in 10-Q filings.annual
tickerNoExchange ticker such as AAPL (class shares as BRK-B, BRK.B or BRK/B). Send ticker or cik.

Output Schema

NameRequiredDescriptionDefault
cikNo
nameNo
noteNo
countNo
errorNoOnly on an error result: an object {code, message}, or the reason string of an x402 PaymentRequired object.
staleNo
cachedNo
periodNo
sourceNo
tickerNo
periodsNo
currencyNo
disclaimerNo
cache_secondsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / periods / items / properties / selection
      Added value: +{
+  "additionalProperties": {
+    "description": "Selection within the priority-anchored category, exact start/end and unit. Only Revenues / RevenueFromContractWithCustomerExcludingAssessedTax and basic or diluted EPS / combined EPS are cross-tag economic aliases. Any observed filing reporting both revenue tags for the same dates with different values marks them as different scopes for that filer; absent scope evidence also disables that alias. Latest filed date wins; equal dates prefer /A forms, then greatest accession as a deterministic tie-break (not filing order), then tag priority; missing filing dates sort first. Excluded concepts/start dates warn only if newer by date or same-date amendment, not accession. A newer eligible alias keeps latest_comparable_fact even with warnings; otherwise a newer excluded fact gives priority_fallback. Contradictory same-tag facts in one filing retain source order with ambiguous_fact, not a new null. Cover-page shares remain matched to the first filing's accession, not the period end.",
+    "properties": {
+      "conflicts": {
+        "description": "Bounded warnings, not proof of a restatement: different economic concepts or starts, contradictory same-tag facts, disagreeing aliases in one filing, or ambiguous cover-page shares. Empty means none of these were observed.",
+        "items": {
+          "enum": [
+            "non_equivalent_concepts",
+            "different_period_start",
+            "ambiguous_fact",
+            "same_filing_values_differ",
+            "ambiguous_cover_shares",
+            null
+          ],
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "maxItems": 5,
+        "type": [
+          "array",
+          "null"
+        ],
+        "uniqueItems": true
+      },
+      "reason": {
+        "enum": [
+          "latest_comparable_fact",
+          "tag_priority_tiebreak",
+          "priority_fallback",
+          "cover_page_accession",
+          "not_reported",
+          null
+        ],
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": [
+      "object",
+      "null"
+    ]
+  },
+  "description": "Per-metric selection reason and bounded conflict codes, keyed by metric name; does not replace the selected metric's filing provenance.",
+  "maxProperties": 13,
+  "propertyNames": {
+    "enum": [
+      "revenue",
+      "grossProfit",
+      "operatingIncome",
+      "netIncome",
+      "epsBasic",
+      "epsDiluted",
+      "totalAssets",
+      "totalLiabilities",
+      "stockholdersEquity",
+      "cash",
+      "operatingCashFlow",
+      "capex",
+      "sharesOutstanding"
+    ]
+  },
+  "type": [
+    "object",
+    "null"
+  ]
+}
  2. Added

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: discloses tie-breaking ('Latest comparable filed fact wins (/A, accession, tag ties)'), null handling for missing metrics, caching up to 6 hours, latency (1-4 s, under 0.1 s cached), price and free-tier limits, and the exact 422/404/503 error semantics including which are not charged.

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?

Front-loaded with purpose and the sibling hand-off, and nearly every clause carries operational information (tie-breaking, errors, limits). Slightly overpacked with pricing/legal boilerplate ('Informational only, not investment advice... no SEC endorsement implied'), which dilutes but does not bury the useful content.

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?

For a read-only lookup with an output schema, everything an agent needs to call it correctly is present: input exclusivity, period semantics, cost, rate limits, latency, and failure modes with charging implications. No call-blocking gaps remain.

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 genuinely new constraints: ticker and cik are mutually exclusive and exactly one must be sent (neither is marked required in the schema), and the 'up to 20' cap on periods. It does not add format detail beyond what the schema's ticker/CIK descriptions already give.

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?

States a specific verb and resource ('Get a US company's reported financials per fiscal year or quarter from SEC EDGAR') and enumerates the returned metrics (revenue, income, EPS, balance sheet, cash flow, capex, shares). It explicitly distinguishes itself from the sibling sec_company_lookup, which handles the registrant and filings.

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

Usage Guidelines5/5

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

Names the alternative tool and the condition that selects it ('For the registrant and filings use sec_company_lookup'), and specifies the input rule 'Send exactly one of ticker or cik'. The annual vs quarterly scope is restated so the agent knows which mode to pick.

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

All Tanod toolsInspect
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