Agent Cookbook

Agents work best when they choose the cheapest source-backed tool that can answer the question, inspect coverage fields before finalizing, and move to richer filing evidence only when the fact layer is not enough.

Prefer cache-backed XBRL facts for numbers, filing sections or documents for prose, tables for tabular disclosures, and paid evidence tools only when the answer requires language-model extraction.

Recipe: One Financial Metric

Use get_metric when the user asks for one number in one period.


1. Call get_metric(ticker, year, quarter, metric_name, date_type).
2. Check status, semantic_status, coverage_status, and coverage_warning.
3. Prefer a match with source_ref and complete coverage.
4. Cite the filing URL or source_ref in the final answer.


{
  "ticker": "AAPL",
  "year": 2025,
  "quarter": 4,
  "metric_name": "Revenue",
  "date_type": "Q"
}

Recipe: Time Series

Use get_metric_series when the user asks for trend, growth, or multiple periods. It is cheaper and more coherent than repeatedly calling get_metric.


1. Call get_metric_series with end_year, end_quarter, periods, and date_type.
2. Inspect period_status and coverage_status for each period.
3. If some periods are missing, answer with the complete periods and name the gap.
4. Do not silently interpolate or fill missing periods.

Recipe: Unknown Metric Name

Use list_metrics before get_metric when the user’s phrase may not match the exact tag or label.


1. Call list_metrics for the filing period.
2. Pick the closest candidate by label, concept, statement role, and unit.
3. Pass the exact candidate into get_metric.
4. If multiple candidates remain plausible, ask the user or return the alternatives.

Recipe: Filing Text With Pagination

Use get_filing_document when an agent needs readable filing text or when a section is too large for one response.


1. Call describe_filing to inspect cached artifacts.
2. Call get_filing_document with section_filter when possible.
3. Respect pagination fields; request the next page instead of assuming truncation is the final answer.
4. Cite section title and accession.

Recipe: Tables

Use table tools when the disclosure is naturally tabular: maturities, segments, leases, debt schedules, or risk tables.


1. Call search_filing_tables with a query or section hint.
2. Call get_filing_tables with table_id for the table that matches the question.
3. Use row and column labels as evidence.
4. Avoid converting table units unless the source unit is explicit.

Recipe: Premium Evidence

Use get_filing_evidence, extraction search, or operational KPI tools when the answer depends on narrative interpretation or non-XBRL KPI language.

⚠️

These tools may be paid or LLM-backed. Do not route anonymous playground traffic or routine numeric lookups into premium extraction paths.

Error Handling

Return the structured error and tell the user the requested filing is not warm. For playground traffic, a 403 cache miss is expected safety behavior.