Skip to main content
Glama
Sign In

KeyVex

by com.keyvex
OverviewDiscussionsAdmin

get_fundamentals

Read-only

Returns XBRL-tagged financial fundamentals from public-company 10-K and 10-Q filings, sourced from SEC EDGAR's company-facts API. Each record is one observation of one concept at one period end. Use this when the user asks about: revenue, profit, margins, cash position, debt, shareholder equity, EPS, share count, operating vs. financing cash flow, or any line-item-level financial state of a public company. Coverage: any company in SEC's ticker list. The S&P 500 is refreshed three times a week; another company is read live from SEC on its first request (US-dollar units only; coverage_warning says so) and stored for later calls. An empty result's coverage_warning says which kind of empty it is. Concepts: a curated 40-concept watchlist covering: - income_statement: Revenues / RevenueFromContractWithCustomer / CostOfRevenue / GrossProfit / OperatingExpenses / R&D / SG&A / OperatingIncomeLoss / InterestExpense / IncomeTaxExpenseBenefit / NetIncomeLoss - balance_sheet: Assets / AssetsCurrent / Cash / AccountsReceivable / Inventory / PP&E / Goodwill / Liabilities / LongTermDebt / StockholdersEquity / CommonStockSharesOutstanding - cash_flow: NetCash{Operating/Investing/Financing}Activities / PaymentsToAcquirePPE (capex) / PaymentsForRepurchaseOfCommonStock / PaymentsOfDividends / DepreciationDepletionAndAmortization - metrics: EarningsPerShareBasic/Diluted, weighted-avg share counts - entity: EntityCommonStockSharesOutstanding (dei taxonomy) Key cautions on the data: - The same concept can appear in multiple units (e.g., 'USD' and 'USD/shares' for EPS). Filter by unit if you need a specific shape. - Many concepts have BOTH year-to-date cumulative observations AND quarterly-period observations on 10-Q filings. The frame field (e.g., 'CY2025Q3') marks the per-quarter point-period observation; rows with empty frame are typically cumulative YTD. - Older filings may use deprecated concept names; KeyVex catalog includes both modern and legacy names where companies migrated (e.g., Revenues AND RevenueFromContractWithCustomerExcludingAssessedTax). - scale_note: on a handful of 2009–2014 share counts that look like the issuer's own scale error (about 1,000× or 1,000,000× its neighbouring filings), a note names the factor and a neighbouring value; value is still as filed. null on every other row. Set latest_only=true to get one record per (ticker × concept) — the most-recent observation. Useful for 'current state' snapshots. Pure-publisher posture: values are AS FILED. We do NOT compute derived ratios (P/E, ROE, ROIC), YoY/QoQ deltas, or 'real' vs nominal versions. Agents calculate those on top.

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": "get_fundamentals"
  }
}

Input Schema

NameRequiredDescriptionDefault
formNoFilter to one filing form.
limitNoDefault 50, max 500.
sinceNoISO date YYYY-MM-DD. Applied to sort_by field.
untilNoISO date YYYY-MM-DD.
tickerNoStock symbol filter, e.g. 'AAPL'. Case-insensitive.
conceptNoExact XBRL tag name (e.g., 'NetIncomeLoss', 'Revenues', 'Assets', 'CashAndCashEquivalentsAtCarryingValue'). Case-sensitive.
sort_byNoDefault period_end.
categoryNoBucket filter when you don't know the exact concept name.
sort_orderNoDefault desc.
company_cikNoSEC CIK number. Alternative to ticker.
fiscal_yearNoFilter to one fiscal year — the year the financials DESCRIBE (the company's own fiscal-year label, derived from the original filing), NOT the filing year. Handles non-December fiscal years: e.g. NVDA's year ending 2024-01-28 is fiscal_year 2024, Apple's ending 2024-09-28 is 2024. For point-in-time period filtering, period_end / since / until and frame are also available.
latest_onlyNoWhen true, return only the most-recent observation per (ticker × concept). Default false.
fiscal_periodNoFilter to one fiscal period.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond annotations by disclosing coverage refresh cadence, live SEC fetch behavior on first request, US-dollar-only limitation, empty-result coverage_warning semantics, YTD vs quarterly frame behavior, unit multiplicity, deprecated concept names, and scale_note quirks. It also states the pure-publisher posture: no derived ratios or deltas are computed.

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 purpose is front-loaded, and the description uses clear sections for coverage, concepts, and cautions. It is long, but most length is justified by the complexity and the absence of an output schema; a few lines, such as the unit-filtering advice, could be tightened.

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?

Complete enough for a complex, no-output-schema tool: it explains what a record represents, how coverage works, what empty results mean, key output-field caveats, and the tool's non-derivation policy. An agent has what it needs to call and interpret this tool correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds useful context for latest_only and concept selection, but it also mentions filtering by unit and the frame field when no unit or frame parameter exists, which slightly muddies parameter guidance.

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?

States a specific verb and resource: returns XBRL-tagged financial fundamentals from SEC 10-K/10-Q company-facts data, with record-level semantics. Purpose is very clear, but it does not explicitly distinguish itself from sibling tools such as get_annual_financial_disclosures or get_bank_financials.

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?

Provides an explicit 'Use this when the user asks about...' list covering revenue, margins, cash flow, EPS, and other financial state questions. It gives strong contextual guidance but does not name alternatives or state when not to use this tool versus overlapping siblings.

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

All KeyVex 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