Docs / Page

Agentic Search Guide

Three-layer retrieval protocol for unstructured financial document analysis.

Worked example: Find revenue guidance in Eli Lilly (LLY) 2024 8-K filings. Each layer narrows the search space before retrieving full content, minimizing token consumption while maximizing relevance.

Layer 1

Document Discovery

Identify which filings exist for the target ticker and period. The SEC filing index covers 11,285 filings across 165 tickers. 8-K filings (material events) are the primary target for qualitative analysis — they contain earnings releases, guidance updates, governance changes, and material agreements.

MCP Tool Call

search_documents { ticker: "LLY" }
// or via REST:
// GET /v1/search_documents?ticker=LLY

Response (excerpt)

{
  "data": [{
    "id": "uuid",
    "ticker": "LLY",
    "filing_date": "2024-08-08",
    "form_type": "8-K",
    "citation_id": "sec245",
    "secondary_labels": ["results_of_operations_2_02", "earnings_guidance"],
    ...
  }, ...],
  "meta": { "total_count": 39 }
}

What you learn: LLY filed 39 documents in 2024. The 8-K with citation_id "sec245" is labeled "results_of_operations_2_02" and "earnings_guidance" — this is the earnings release containing revenue guidance. Note the document's accession number or citation_id for Layer 2.

Credit cost: 1

Layer 2

Page Map — read_source_outline

Retrieve every page's description and keywords — without the full page content. For a typical 8-K with ~200 pages, this returns approximately 5,000 tokens. Scan the descriptions to identify which pages contain the information you need.

MCP Tool Call

read_source_outline { identifier: "0000059478-24-000123" }
// Uses accession_number (preferred) or document_id (UUID)
// GET /v1/read_source_outline/0000059478-24-000123

Response (excerpt — 3 of ~200 pages)

{
  "document_id": "uuid",
  "accession_number": "0000059478-24-000123",
  "ticker": "LLY",
  "filing_date": "2024-08-08",
  "pages": [
    { "page_no": "page1", "description": "Cover page — Eli Lilly and Company",
      "keywords": ["cover", "securities", "registrant"] },
    { "page_no": "page42", "description": "Q2 2024 revenue breakdown by product — Mounjaro $3.1B, Trulicity $1.5B",
      "keywords": ["revenue", "mounjaro", "trulicity", "q2", "product"] },
    { "page_no": "page47", "description": "FY2024 revenue guidance raised to $45.4B–$46.6B",
      "keywords": ["guidance", "revenue", "fy2024", "raised", "outlook"] },
    ...
  ],
  "meta": { "page_count": 197, "data_freshness": "2026-05-12T03:57:54+00" }
}

What you learn: Page 47 contains the FY2024 revenue guidance — exactly what we're looking for. Page 42 has the product-level breakdown for context. The other 195 pages cover risk factors, legal proceedings, exhibits, and signatures — we skip them.

Layer 2 Alternative — Keyword Filter

When you know your keyword, use search_keyword_in_source instead. It runs full-text search across all page_content and returns only matching pages:

search_keyword_in_source { identifier: "0000059478-24-000123", keyword: "revenue guidance" }
// Returns page_no + description pairs for pages matching the keyword
// Faster than scanning 200 pages when you know what to search for

Credit cost: 2 (fixed, regardless of page count)

Layer 3

Deep Read — read_source_pages

Fetch the full markdown page_content for the specific pages identified in Layer 2. Each page includes [[Table{idx}]] markers for embedded tables and a citation_id for provenance tracking.

MCP Tool Call

read_source_pages {
  identifier: "0000059478-24-000123",
  pages: "page42,page47"
}
// GET /v1/read_source_pages/0000059478-24-000123?pages=page42,page47

Response (page47 excerpt)

{
  "data": [{
    "page_no": "page47",
    "page_content": "## Financial Guidance\n\nEli Lilly and Company today
      raised its full-year 2024 revenue guidance to $45.4 billion–$46.6 billion,
      reflecting strong performance across Mounjaro, Zepbound, and Jardiance.
      Non-GAAP EPS guidance was raised to $16.10–$16.60.\n\n
      [[Table12]]\n\nThe revised guidance reflects...",
    "labels": { "general": { "keywords": ["guidance", "fy2024", "revenue"] } },
    "citation_id": "agentii://source/uuid?page=page47&accession=0000059478-24-000123"
  }]
}

What you learn: LLY raised FY2024 revenue guidance to $45.4B–$46.6B and non-GAAP EPS to $16.10–$16.60. The citation_id provides a permanent, traceable reference to this specific page in this specific filing — suitable for institutional research reports.

Credit cost: 2 (2 pages × 1 credit/page)

Walkthrough Summary

Layer	Operation	Credits	Tokens
L1	search_documents → find 8-K filings	1	~500
L2	read_source_outline → scan 197 page descriptions	2	~5,000
L3	read_source_pages → fetch 2 specific pages	2	~3,000
Total		5 credits	~8,500

Compare to retrieving all 197 pages directly (197 credits, ~500K tokens). The three-layer protocol achieves 97% token savings and 97.5% credit savings by filtering before retrieving full content.

Multi-Period Alternative: search_cross_period

For comparisons across fiscal periods, search_cross_period runs the full three-layer protocol in parallel for each period. Use get_company_fiscal_calendar to discover the correct fiscal period format before calling.

search_cross_period {
  ticker: "LLY",
  query: "revenue guidance",
  fiscal_periods: ["FY2022", "FY2023", "FY2024", "FY2025"]
}
// 4 periods × 1 credit = 4 credits (only successful periods)

For structured financial metrics (Revenue, EPS, margins), use search_xbrl_facts instead — it covers all periods in a single call.