Skip to main content
Glama

NS Pros MCP Gateway

noirlab-datalab__company_facts

TYPED, DETERMINISTIC financial facts for a US public company for an EXPLICITLY NAMED reporting period, "Apple revenue for fiscal 2023", "Walmart net income FY2026 Q3", "Microsoft cash at the end of fiscal 2024". PREFER OVER entity_profile / get_company_financials whenever the period matters: those answer "the most recent figures" and will happily hand back FY2025 when you asked about FY2019, and neither separates a discrete quarter from a year-to-date figure. This one refuses instead, it NEVER s

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "period": {
        "type": "annual",
        "fiscal_year": 2023
      },
      "company": "AAPL",
      "attribute": "revenue"
    },
    "name": "noirlab-datalab__company_facts"
  }
}

Input Schema

NameRequiredDescriptionDefault
as_ofNoPast ISO timestamp with timezone. Replay the latest answer actually recorded by that instant; no invented history or live fallback.
basisNoOnly "consolidated" in v1. Segment and product-level figures are XBRL-dimensioned and are not reachable through this contract at any concept.
periodYesThe reporting period, stated explicitly. There is no default and no "latest", that is the point of this tool.
companyYesTicker ("AAPL"), 10-digit CIK ("0000320193"), or company name. A name that matches two filers equally well returns status "ambiguous" with both named rather than guessing, pass a ticker or CIK to be certain.
max_ageNoMaximum age in seconds of the upstream publication, not our fetch. Older or undated facts are withheld.
attributeYesWhich figure. "revenue" = total consolidated revenue; "net_income" = net income (loss); "cash" = cash and cash equivalents at the period end; "gross_profit"; "operating_income"; "eps_diluted" (diluted EPS, unit USD/shares, never derived or summed); "capex" (cash paid for PP&E); "operating_cash_flow" (net cash from operating activities); "long_term_debt" (the noncurrent balance-sheet line where the filer tags it, else total long-term debt, `fact.measure` says which); "shares_outstanding" (dei cover-page common shares, unit "shares", as of the COVER DATE rather than the period end).
freshnessNocached (default) permits an eligible stored answer; fresh requires an upstream refresh and never silently falls back to stale data.
restatementNoDefault "as_amended", the latest filed figure for the period, with everything it superseded listed. "as_originally_reported" takes the first filing instead.
exclude_publishersNoPublisher ids forbidden for fact retrieval: sec, fmp, alphavantage. Case and surrounding whitespace are normalized; unknown ids are refused. Excluding sec currently leaves no eligible fact source and returns unavailable/sources_excluded with the selection reasons. Identity and fiscal-calendar lookups may still use SEC; no excluded financial concept is fetched.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does add real behavior: deterministic typing, and that it 'refuses instead' of substituting a nearby period rather than returning a plausible wrong answer. However, the disclosure is cut off mid-sentence ('it NEVER s'), so the refusal contract, return statuses, and any auth/rate-limit context are left incomplete.

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

Conciseness3/5

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

The key routing information is front-loaded in the first two sentences, which is good structure. But the prose is heavy on all-caps emphasis and run-on clauses, and the text terminates mid-word, which reads as a broken/truncated definition rather than a deliberately terse one.

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

Completeness3/5

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

This is a 9-parameter tool with a nested period object, four enums, and no output schema, so the description should explain what comes back — yet it never describes the response shape, the 'ambiguous'/'unavailable' statuses, or how as_of/freshness/restatement interact in the result. The truncation compounds the gap, though the 100%-covered schema partially compensates.

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% and the parameter descriptions are unusually rich (fiscal_year defined as the filer's own calendar, fiscal_quarter rejected when annual, as_of semantics, exclude_publishers behavior), so the schema already does the heavy lifting. The description itself adds no parameter-level meaning beyond the illustrative query strings, so the baseline 3 applies.

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 description names a specific verb and resource ('TYPED, DETERMINISTIC financial facts for a US public company') and pins the scope to an 'EXPLICITLY NAMED reporting period', reinforced by three concrete example queries. It also explicitly separates itself from entity_profile / get_company_financials, so an agent can route without opening any 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 states the selection rule outright: 'PREFER OVER entity_profile / get_company_financials whenever the period matters', and justifies it with the concrete failure modes of those siblings (returning FY2025 when FY2019 was asked, conflating discrete quarters with year-to-date figures). That is an explicit when-to-use plus named alternatives and their disqualifying conditions.

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.