Skip to main content
Glama

Crypto & Macro Market Data (Tanod)

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

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "sec_financials"
  }
}

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.
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. Changed10 schema fields changed
    • removedInput schema / properties / cik / default
      Removed value: -null
    • removedInput schema / properties / cik / title
      Removed value: -"Cik"
    • changedInput schema / properties / limit / description
      Previous value: -"Newest periods to return, 1-20 (default 4)."New value: +"Newest periods to return."
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • removedInput schema / properties / period / title
      Removed value: -"Period"
    • removedInput schema / properties / ticker / default
      Removed value: -null
    • removedInput schema / properties / ticker / title
      Removed value: -"Ticker"
    • removedInput schema / title
      Removed value: -"sec_financialsArguments"
    • removedOutput schema / properties / periods / items
      Removed value: -{
      -  "properties": {
      -    "accession": {
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    },
      -    "fiscalPeriod": {
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    },
      -    "fiscalYear": {
      -      "type": [
      -        "integer",
      -        "null"
      -      ]
      -    },
      -    "form": {
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    },
      -    "metrics": {
      -      "additionalProperties": {
      -        "properties": {
      -          "accession": {
      -            "type": [
      -              "string",
      -              "null"
      -            ]
      -          },
      -          "filed": {
      -            "type": [
      -              "string",
      -              "null"
      -            ]
      -          },
      -          "fiscalPeriod": {
      -            "type": [
      -              "string",
      -              "null"
      -            ]
      -          },
      -          "fiscalYear": {
      -            "type": [
      -              "integer",
      -              "null"
      -            ]
      -          },
      -          "form": {
      -            "type": [
      -              "string",
      -              "null"
      -            ]
      -          },
      -          "periodEnd": {
      -            "type": [
      -              "string",
      -              "null"
      -            ]
      -          },
      -          "periodStart": {
      -            "type": [
      -              "string",
      -              "null"
      -            ]
      -          },
      -          "tag": {
      -            "type": [
      -              "string",
      -              "null"
      -            ]
      -          },
      -          "taxonomy": {
      -            "type": [
      -              "string",
      -              "null"
      -            ]
      -          },
      -          "unit": {
      -            "type": [
      -              "string",
      -              "null"
      -            ]
      -          },
      -          "value": {
      -            "type": [
      -              "number",
      -              "null"
      -            ]
      -          }
      -        },
      -        "type": [
      -          "object",
      -          "null"
      -        ]
      -      },
      -      "description": "revenue, grossProfit, operatingIncome, netIncome, epsBasic, epsDiluted, totalAssets, totalLiabilities, stockholdersEquity, cash, operatingCashFlow, capex, sharesOutstanding",
      -      "type": [
      -        "object",
      -        "null"
      -      ]
      -    },
      -    "periodEnd": {
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    },
      -    "selection": {
      -      "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"
      -      ]
      -    }
      -  },
      -  "type": [
      -    "object",
      -    "null"
      -  ]
      -}
    • removedOutput schema / properties / source / properties
      Removed value: -{
      -  "license": {
      -    "type": [
      -      "string",
      -      "null"
      -    ]
      -  },
      -  "name": {
      -    "type": [
      -      "string",
      -      "null"
      -    ]
      -  },
      -  "notice": {
      -    "type": [
      -      "string",
      -      "null"
      -    ]
      -  },
      -  "terms": {
      -    "type": [
      -      "string",
      -      "null"
      -    ]
      -  },
      -  "url": {
      -    "type": [
      -      "string",
      -      "null"
      -    ]
      -  }
      -}
  2. 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"
      +  ]
      +}
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description adds substantial context on top: caching up to 6 hours, typical 1-4 s latency, the tie-breaking rule for duplicate filed facts, warning emission for excluded concepts, null-valued missing metrics, and charging semantics per error class (422/404 not charged, 503 not charged). That is exactly the extra behavioral detail annotations cannot convey.

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?

Purpose is front-loaded in the first sentence and the sibling routing follows immediately, which is the right order. It is somewhat overloaded, however: the vendor "utilpeek:" prefix, pricing, free-tier quota and disclaimer boilerplate are packed into semicolon-chained clauses that make the core capability harder to scan on a first read.

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-shape explanation is not required, yet the description still enumerates the metric families and null behavior. Combined with coverage of source, caching, latency, pricing, error codes and split-credit rules, an agent has everything needed to call it correctly and to interpret failures.

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 adds meaning the schema does not encode: the mutual-exclusivity rule ("Send exactly one of ticker or cik") is absent from the schema, which declares no required fields and no oneOf constraint. It also restates the up-to-20 cap and the annual/quarterly definition, which are useful but largely duplicative of 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?

States a specific verb and resource: "Get a US company's reported financials per fiscal year or quarter from SEC EDGAR," and immediately names the enumerated metrics (revenue, income, EPS, balance sheet, cash flow, capex, shares). It also differentiates from the sibling by routing registrant/filing questions to sec_company_lookup, so the agent can separate the two without opening either schema.

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?

It explicitly names the alternative ("For the registrant and filings use sec_company_lookup") and the condition that selects it, which is the key routing decision for an agent. It also states the input contract ("Send exactly one of ticker or cik") and the annual-vs-quarterly semantics, leaving little to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.