@cyanheads/secedgar-mcp-server 0.12.2 → 0.12.4

package/dist/mcp-server/tools/definitions/search-filings.tool.js

@@ -1,11 +1,33 @@
 /**
- * @fileoverview Full-text search across all EDGAR filing documents since 1993.
+ * @fileoverview Search EDGAR filings since 1993 — EFTS full-text for 2001-present,
+ * archive-backed browse (submissions history + quarterly full-index) for pre-2001
+ * date ranges.
  * @module mcp-server/tools/definitions/search-filings
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode, validationError } from '@cyanheads/mcp-ts-core/errors';
 import { getCanvasBridge, toDatasetField } from '../../../services/canvas-bridge/canvas-bridge.js';
-import { getEdgarApiService } from '../../../services/edgar/edgar-api-service.js';
+import { getEdgarApiService, quartersInRange, selectArchivePages, } from '../../../services/edgar/edgar-api-service.js';
+/**
+ * The EFTS full-text index only covers filings from this date onward, even
+ * though the archives reach 1993. A date range entirely before this floor is
+ * routed to the archive-backed paths; a range straddling it is rejected (#77).
+ */
+const EFTS_FULLTEXT_FLOOR = '2001-01-01';
+/**
+ * Cap on submissions archive pages fetched in one call (pre-2001 entity-scoped
+ * arm) — bounds latency and the rate-limited request budget. Mirrors the same
+ * constant in company-search.tool.ts. Pre-2001 pages are a filer's oldest, so
+ * the cap rarely binds; when it does, `dataset.truncated` discloses it.
+ */
+const ARCHIVE_PAGE_SCAN_CAP = 10;
+/**
+ * Cap on quarterly full-index files fetched in one unscoped pre-2001 browse.
+ * Each `master.idx` is a multi-MB whole-quarter download and is not
+ * form-filterable server-side, so this arm is the heaviest — the cap bounds it
+ * hard, and `dataset.truncated` discloses when older quarters went unscanned.
+ */
+const FULL_INDEX_QUARTER_SCAN_CAP = 8;
 function eftsHitToRow(hit) {
     const displayName = hit._source.display_names?.[0] || '';
     return {
@@ -19,8 +41,47 @@ function eftsHitToRow(hit) {
         file_description: hit._source.file_description ?? null,
         sic: hit._source.sics?.[0] ?? null,
         location: hit._source.biz_locations?.[0] ?? null,
+        source: 'efts',
+    };
+}
+/** Map a fully-keyed {@link SearchRow} to an inline output row (nulls → omitted optionals). */
+function toInlineResult(row) {
+    return {
+        accession_number: row.accession_number,
+        ...(row.form != null && { form: row.form }),
+        filing_date: row.filing_date,
+        ...(row.period_ending != null && { period_ending: row.period_ending }),
+        company_name: row.company_name,
+        cik: row.cik ?? '',
+        ...(row.ticker != null && { ticker: row.ticker }),
+        ...(row.file_description != null && { file_description: row.file_description }),
+        ...(row.sic != null && { sic: row.sic }),
+        ...(row.location != null && { location: row.location }),
+        source: row.source,
     };
 }
+/**
+ * True when a filing's form matches a requested form, counting amendments
+ * (requested "10-K" matches "10-K" and "10-K/A"), mirroring EFTS forms
+ * semantics so the archive-backed arms honor the same forms contract as the
+ * post-2001 full-text path.
+ */
+function formMatches(filingForm, requestedForms) {
+    const f = filingForm.toUpperCase();
+    return requestedForms.some((req) => {
+        const r = req.toUpperCase();
+        return f === r || f.startsWith(`${r}/`);
+    });
+}
+/** Count filings by form, dropping the field when nothing carried a form. */
+function buildFormDistribution(forms) {
+    const dist = {};
+    for (const form of forms) {
+        if (form)
+            dist[form] = (dist[form] ?? 0) + 1;
+    }
+    return Object.keys(dist).length > 0 ? dist : undefined;
+}
 /**
  * EDGAR's `display_names[0]` embeds the ticker(s) and CIK in trailing parentheticals
  * (e.g., "Apple Inc.  (AAPL)  (CIK 0000320193)"). Strip them so consumers see a clean
@@ -84,8 +145,183 @@ async function resolveEntityTargeting(query, ctx) {
     }
     return { query };
 }
+/**
+ * Shared tail for the archive-backed arms: sort the fully-matched rows, slice
+ * the inline window, recompute the form distribution, register the full set to
+ * the canvas (source-tagged), and emit the query echo / boundary notices.
+ * `scanTruncated` (a scan cap bound before the range was exhausted) drives both
+ * `total_is_exact` and the dataframe `truncated` flag.
+ */
+async function finishArchiveResult(ctx, args) {
+    // Full-index and submissions have no relevance score, so relevance collapses
+    // to date-descending; only an explicit ascending request reorders.
+    const sorted = [...args.matched].sort((a, b) => args.sort === 'filing_date_asc'
+        ? a.filing_date.localeCompare(b.filing_date)
+        : b.filing_date.localeCompare(a.filing_date));
+    const total = sorted.length;
+    const totalIsExact = !args.scanTruncated;
+    const sliced = sorted.slice(args.offset, args.offset + args.limit);
+    const results = sliced.map(toInlineResult);
+    const formDistribution = buildFormDistribution(sorted.map((row) => row.form));
+    let dataset;
+    const bridge = getCanvasBridge();
+    if (bridge && sorted.length > args.limit) {
+        const registered = await bridge.registerDataframe(ctx, {
+            rows: sorted,
+            sourceTool: 'secedgar_search_filings',
+            queryParams: args.queryParams,
+            truncated: args.scanTruncated,
+        });
+        if (registered)
+            dataset = { ...toDatasetField(registered), truncated: args.scanTruncated };
+    }
+    ctx.enrich.echo(args.effectiveQuery);
+    if (total === 0) {
+        ctx.enrich.notice(`No filings matched ${args.zeroHitCriteria}. ${args.coverageNote}`);
+    }
+    else if (results.length === 0 && args.offset >= sorted.length) {
+        ctx.enrich.notice(`Offset (${args.offset}) exceeds the ${sorted.length} matched filings. ${total} filings matched — lower the offset or query the full set via secedgar_dataframe_query.`);
+    }
+    else if (total > results.length) {
+        ctx.enrich.truncated({
+            shown: results.length,
+            cap: args.limit,
+            guidance: args.scanTruncated
+                ? `${args.coverageNote} The scan hit its cap before exhausting the range — older filings may exist beyond the scanned window. Narrow the range, or query the dataframe.`
+                : `${args.coverageNote} Query the full matched set via secedgar_dataframe_query, or page with offset.`,
+        });
+    }
+    return {
+        total,
+        total_is_exact: totalIsExact,
+        results,
+        form_distribution: formDistribution,
+        dataset,
+    };
+}
+/**
+ * Pre-2001 entity-scoped arm: resolve the CIK's full submissions history (the
+ * `recent` window plus the `filings.files[]` archive pages reused from #78) and
+ * filter by form + date. Reuses `getSubmissions`/`selectArchivePages`/
+ * `fetchArchivePage` as-is. Rows are tagged `source: 'submissions'`; the
+ * EFTS-only fields (period_ending, ticker, file_description, sic, location) are
+ * left null for a uniform archive-row shape.
+ */
+async function serveSubmissionsArchive(ctx, args) {
+    const api = getEdgarApiService();
+    const submissions = await api.getSubmissions(args.entityCik);
+    const companyName = submissions.name;
+    const forms = args.forms?.length ? args.forms : undefined;
+    const rows = [];
+    const pushBlock = (block) => {
+        for (let i = 0; i < block.accessionNumber.length; i++) {
+            const form = block.form[i] ?? '';
+            const filingDate = block.filingDate[i] ?? '';
+            if (filingDate < args.startDate || filingDate > args.endDate)
+                continue;
+            if (forms && !formMatches(form, forms))
+                continue;
+            rows.push({
+                accession_number: block.accessionNumber[i] ?? '',
+                form: form || null,
+                filing_date: filingDate,
+                period_ending: null,
+                company_name: companyName,
+                cik: args.entityCik,
+                ticker: null,
+                file_description: null,
+                sic: null,
+                location: null,
+                source: 'submissions',
+            });
+        }
+    };
+    pushBlock(submissions.filings.recent);
+    // Older filings live in the archive pages covering the requested pre-2001 range.
+    const pages = selectArchivePages(submissions.filings.files, args.startDate, args.endDate);
+    const pageLimit = Math.min(pages.length, ARCHIVE_PAGE_SCAN_CAP);
+    const scanTruncated = pages.length > pageLimit;
+    for (let i = 0; i < pageLimit; i++) {
+        const page = pages[i];
+        if (!page)
+            break;
+        pushBlock(await api.fetchArchivePage(page.name));
+    }
+    const formsNote = forms ? `, forms ${forms.join(', ')}` : '';
+    return finishArchiveResult(ctx, {
+        matched: rows,
+        sort: args.sort,
+        limit: args.limit,
+        offset: args.offset,
+        scanTruncated,
+        queryParams: {
+            entity_cik: args.entityCik,
+            forms: args.forms,
+            start_date: args.startDate,
+            end_date: args.endDate,
+            source: 'submissions',
+        },
+        effectiveQuery: `(pre-2001 archive: CIK ${args.entityCik}${formsNote}, ${args.startDate} to ${args.endDate})`,
+        coverageNote: 'Served from the entity submissions history — full-text search covers 2001-present only.',
+        zeroHitCriteria: `CIK ${args.entityCik}${forms ? `, forms [${forms.join(', ')}]` : ''}, dates ${args.startDate} to ${args.endDate}`,
+    });
+}
+/**
+ * Pre-2001 unscoped browse arm: fetch the quarterly full-index (`master.idx`)
+ * files spanning the range and filter by form + date client-side (the index is
+ * not form-filterable server-side). Bounded by FULL_INDEX_QUARTER_SCAN_CAP —
+ * the heaviest arm. Rows are tagged `source: 'full-index'`.
+ */
+async function serveFullIndexBrowse(ctx, args) {
+    const api = getEdgarApiService();
+    const quarters = quartersInRange(args.startDate, args.endDate);
+    const quarterLimit = Math.min(quarters.length, FULL_INDEX_QUARTER_SCAN_CAP);
+    const scanTruncated = quarters.length > quarterLimit;
+    const rows = [];
+    for (let i = 0; i < quarterLimit; i++) {
+        const quarter = quarters[i];
+        if (!quarter)
+            break;
+        const entries = await api.fetchFullIndexQuarter(quarter.year, quarter.quarter);
+        for (const entry of entries) {
+            if (entry.filingDate < args.startDate || entry.filingDate > args.endDate)
+                continue;
+            if (!formMatches(entry.form, args.forms))
+                continue;
+            rows.push({
+                accession_number: entry.accessionNumber,
+                form: entry.form || null,
+                filing_date: entry.filingDate,
+                period_ending: null,
+                company_name: entry.companyName,
+                cik: entry.cik,
+                ticker: null,
+                file_description: null,
+                sic: null,
+                location: null,
+                source: 'full-index',
+            });
+        }
+    }
+    return finishArchiveResult(ctx, {
+        matched: rows,
+        sort: args.sort,
+        limit: args.limit,
+        offset: args.offset,
+        scanTruncated,
+        queryParams: {
+            forms: args.forms,
+            start_date: args.startDate,
+            end_date: args.endDate,
+            source: 'full-index',
+        },
+        effectiveQuery: `(pre-2001 full-index browse: forms ${args.forms.join(', ')}, ${args.startDate} to ${args.endDate})`,
+        coverageNote: 'Served from the quarterly EDGAR full-index — full-text search covers 2001-present only.',
+        zeroHitCriteria: `forms [${args.forms.join(', ')}], dates ${args.startDate} to ${args.endDate}`,
+    });
+}
 export const searchFilingsTool = tool('secedgar_search_filings', {
-    description: 'Search the full-text index of EDGAR filings since 1993. Supports exact phrases, boolean operators, wildcards, and entity targeting (ticker:AAPL or cik:320193 in query).',
+    description: 'Search EDGAR filings since 1993. Full-text search covers 2001-present (the EFTS index floor); pre-2001 date ranges (to 1993) are served from the archives by form and entity/date — pre-2001 full-text matching requires entity scope (ticker:/cik:). Supports exact phrases, boolean operators, wildcards, and entity targeting (ticker:AAPL or cik:320193 in query).',
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     // Agent-facing context for the success path — the query as EDGAR executed it and
     // an optional notice for empty results. Populated via ctx.enrich so it reaches
@@ -121,13 +357,43 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
             when: 'A cik: targeting token in the query is not a 1-10 digit number',
             recovery: 'Pass a numeric CIK such as cik:320193 — find it with secedgar_company_search if unknown.',
         },
+        {
+            reason: 'missing_criteria',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'Neither a full-text query nor a forms filter was provided (a date range cannot stand alone)',
+            recovery: 'Provide search terms, or browse by form type (forms: ["S-1"]) or entity (ticker:AAPL / cik:320193 in the query) — optionally narrowed by date.',
+        },
+        {
+            reason: 'straddling_date_range',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'The date range crosses 2001-01-01, spanning both the EFTS full-text era and the pre-2001 archives',
+            recovery: 'Split at 2001-01-01: run one search for the ≥2001 side and another for the <2001 side, then combine the results.',
+        },
+        {
+            reason: 'pre2001_full_text_unscoped',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A pre-2001 date range carries free-text terms with no entity scope — no pre-2001 full-text index exists',
+            recovery: 'Add ticker: or cik: entity scope to the query, or drop the text terms to browse pre-2001 filings by form and date.',
+        },
+        {
+            reason: 'pre2001_full_text_scoped',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'A pre-2001 date range carries free-text terms alongside entity scope — local document matching is not yet supported',
+            recovery: "Drop the text terms to browse this entity's pre-2001 filings by form and date.",
+        },
     ],
     input: z.object({
         query: z
-            .string()
-            .trim()
-            .min(1, 'Query cannot be blank')
-            .describe('Full-text search query. Supports: exact phrases ("material weakness"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), entity targeting (ticker:AAPL or cik:320193 in the query). Terms are AND\'d by default.'),
+            .union([
+            z.literal(''),
+            z
+                .string()
+                .trim()
+                .min(1, 'Query cannot be blank')
+                .describe('Full-text search query. Supports: exact phrases ("material weakness"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), entity targeting (ticker:AAPL or cik:320193 in the query). Terms are AND\'d by default.'),
+        ])
+            .optional()
+            .describe('Full-text search query. Optional — omit (or pass "") to browse by form type and/or entity instead, e.g. every S-1 in a date window, or a company\'s filings via ticker:/cik:. A date range alone is not a valid search; pair it with forms or entity targeting. Full-text terms match only filings from 2001 onward (the EFTS index floor); for a pre-2001 date range, drop the text terms (browse by form/date) or add ticker:/cik: entity scope. When present, supports exact phrases ("material weakness"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), and entity targeting (ticker:AAPL or cik:320193 in the query); terms are AND\'d by default.'),
         forms: z
             .array(z.string())
             .optional()
@@ -163,13 +429,15 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
         sort: z
             .enum(['filing_date_desc', 'filing_date_asc', 'relevance'])
             .default('filing_date_desc')
-            .describe('Result ordering. "filing_date_desc" (default) returns most recent first. "filing_date_asc" returns oldest first. "relevance" returns SEC\'s native search-score order, which weights term match strength over recency. Date sorts re-order the top 100 hits returned by the search index — for broad queries with more than 100 matches and no entity targeting, date-newest filings may sit outside that window. Entity targeting (ticker:/cik:) or a narrower query keeps matches inside the window when absolute recency matters.'),
+            .describe('Result ordering. "filing_date_desc" (default) returns most recent first. "filing_date_asc" returns oldest first. "relevance" returns SEC\'s native search-score order, which weights term match strength over recency. Date sorts re-order the top 100 hits returned by the search index — for broad queries with more than 100 matches and no entity targeting, date-newest filings may sit outside that window. Entity targeting (ticker:/cik:) or a narrower query keeps matches inside the window when absolute recency matters. On the no-query browse path (forms/entity only), EFTS has no relevance signal — every hit scores null — and returns filings in natural date-descending order, so all sort modes effectively yield newest-first. Pre-2001 archive results carry no relevance score either, so relevance collapses to date-descending there.'),
     }),
     output: z.object({
         total: z
             .number()
-            .describe("Total matching filings (capped at 10,000). Entity targeting (ticker:/cik:) scopes server-side via the EFTS ciks param, so this is the entity's exact match count up to the cap."),
-        total_is_exact: z.boolean().describe('False only when total hits the 10,000 cap.'),
+            .describe("Total matching filings. On the full-text (2001+) path this is capped at 10,000; entity targeting (ticker:/cik:) scopes server-side via the EFTS ciks param, so it is the entity's exact match count up to the cap. On a pre-2001 archive path it is the exact count within the scanned window (see total_is_exact)."),
+        total_is_exact: z
+            .boolean()
+            .describe('False when total is a lower bound — the full-text path hit its 10,000 cap, or a pre-2001 archive scan hit its page/quarter cap before exhausting the range.'),
         results: z
             .array(z
             .object({
@@ -184,7 +452,7 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
             period_ending: z
                 .string()
                 .optional()
-                .describe('Period the filing reports on (YYYY-MM-DD). Absent for filings without a reporting period (e.g., proxy statements, ownership reports).'),
+                .describe('Period the filing reports on (YYYY-MM-DD). Absent for filings without a reporting period (e.g., proxy statements, ownership reports) and for all pre-2001 archive-sourced rows (source submissions/full-index), which carry no period field.'),
             company_name: z
                 .string()
                 .describe('Filing entity, with ticker/CIK parentheticals stripped.'),
@@ -192,21 +460,25 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
             ticker: z
                 .string()
                 .optional()
-                .describe('Primary ticker symbol parsed from the EFTS display name. Absent for private filers, foreign filers without a US listing, and filings whose display name omits the ticker parenthetical. For multi-class issuers (e.g., BRK-A / BRK-B), this is the first class listed.'),
+                .describe('Primary ticker symbol parsed from the EFTS display name. Absent for private filers, foreign filers without a US listing, filings whose display name omits the ticker parenthetical, and all pre-2001 archive-sourced rows. For multi-class issuers (e.g., BRK-A / BRK-B), this is the first class listed.'),
             file_description: z
                 .string()
                 .optional()
-                .describe('SEC-provided description of the matching document (e.g., "EX-99.1"). Absent when SEC published none.'),
+                .describe('SEC-provided description of the matching document (e.g., "EX-99.1"). Absent when SEC published none, and for pre-2001 archive-sourced rows.'),
             sic: z
                 .string()
                 .optional()
-                .describe('SIC industry code for the filer. Absent for filers without a classification.'),
+                .describe('SIC industry code for the filer. Absent for filers without a classification, and for pre-2001 archive-sourced rows.'),
             location: z
                 .string()
                 .optional()
-                .describe('Business location (state or country code). Absent when SEC has no location for this filer.'),
+                .describe('Business location (state or country code). Absent when SEC has no location for this filer, and for pre-2001 archive-sourced rows.'),
+            source: z
+                .enum(['efts', 'submissions', 'full-index'])
+                .optional()
+                .describe('Which EDGAR backend served this row: "efts" (2001+ full-text index), "submissions" (a pre-2001 entity-scoped filing history), or "full-index" (a pre-2001 unscoped quarterly index browse). Provenance is carried into the canvas dataframe as a `source` column.'),
         })
-            .describe('One matching filing hit from the full-text search index.'))
+            .describe('One matching filing hit.'))
             .describe('Matching filings.'),
         form_distribution: z
             .record(z.string(), z.number())
@@ -221,19 +493,70 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
             expires_at: z.string().describe('ISO 8601 expiry timestamp.'),
             truncated: z
                 .boolean()
-                .describe('True when EFTS reported more text matches than the window we already fetched — additional rows exist beyond the dataframe. Page further with `offset` for the inline view; the canvas dataframe is bounded by the single response window.'),
+                .describe('True when more matches exist beyond the materialized set — the full-text window was exceeded, or a pre-2001 archive scan hit its cap. Each row carries a `source` column so provenance survives into secedgar_dataframe_query.'),
         })
             .optional()
-            .describe('Canvas dataframe holding the hits already fetched for the inline response. Absent when total ≤ inline limit, canvas is unavailable, or materialization failed. The dataframe contains the raw EFTS results (entity-scoped server-side via the ciks param when ticker:/cik: was used) — query with secedgar_dataframe_query SQL.'),
+            .describe('Canvas dataframe holding the fetched hits (full-text window, or the full pre-2001 archive match set), each tagged with its `source`. Absent when total ≤ inline limit, canvas is unavailable, or materialization failed. Query with secedgar_dataframe_query SQL.'),
     }),
     async handler(input, ctx) {
         // Validate date range: both or neither
         if ((input.start_date && !input.end_date) || (!input.start_date && input.end_date)) {
             throw ctx.fail('invalid_date_range', 'Both start_date and end_date are required when filtering by date.', { ...ctx.recoveryFor('invalid_date_range') });
         }
+        // Browse mode (#79): EFTS accepts a forms-only or entity-scoped request with no
+        // full-text term, but rejects one with neither ("Blank search not valid"). Guard
+        // the both-absent shape here — checked against the RAW query/forms (before the
+        // entity token is stripped), so a bare cik:/ticker: query still passes (it has raw
+        // content even though it strips to blank). A date range does not stand alone.
+        if (!input.query?.trim() && !input.forms?.length) {
+            throw ctx.fail('missing_criteria', 'A full-text query or a forms filter is required — a date range alone is not a valid search.', { ...ctx.recoveryFor('missing_criteria') });
+        }
         // Resolve ticker:/cik: entity targeting → stripped query + CIK for the
         // server-side ciks param. Throws typed validation errors on bad tokens (#61).
-        const { query, entityCik } = await resolveEntityTargeting(input.query, ctx);
+        // Default to '' so a browse request (undefined query) resolves cleanly.
+        const { query, entityCik } = await resolveEntityTargeting(input.query ?? '', ctx);
+        const api = getEdgarApiService();
+        // Date-based routing at the EFTS full-text floor (2001-01-01). EFTS only
+        // indexes filings from 2001; a range entirely before it is served from the
+        // archives, a range crossing it is rejected with a split instruction (#77).
+        const startDate = input.start_date || undefined;
+        const endDate = input.end_date || undefined;
+        if (startDate && endDate && endDate < EFTS_FULLTEXT_FLOOR) {
+            const hasFreeText = query.trim().length > 0;
+            if (hasFreeText) {
+                // No pre-2001 full-text index exists. Reject honestly rather than silently
+                // dropping the text terms; bounded local matching is a deferred follow-up.
+                if (entityCik) {
+                    throw ctx.fail('pre2001_full_text_scoped', "Full-text matching of pre-2001 filings is not yet supported. Drop the text terms to browse this entity's pre-2001 filings by form and date.", { ...ctx.recoveryFor('pre2001_full_text_scoped') });
+                }
+                throw ctx.fail('pre2001_full_text_unscoped', 'Full-text search is unavailable before 2001 (the EFTS index starts at 2001-01-01). For pre-2001 filings, add ticker:/cik: entity scope, or drop the text terms to browse by form and date.', { ...ctx.recoveryFor('pre2001_full_text_unscoped') });
+            }
+            if (entityCik) {
+                return await serveSubmissionsArchive(ctx, {
+                    entityCik,
+                    forms: input.forms,
+                    startDate,
+                    endDate,
+                    sort: input.sort,
+                    limit: input.limit,
+                    offset: input.offset,
+                });
+            }
+            // Unscoped + no free text → forms are guaranteed present by the missing_criteria guard.
+            return await serveFullIndexBrowse(ctx, {
+                forms: input.forms ?? [],
+                startDate,
+                endDate,
+                sort: input.sort,
+                limit: input.limit,
+                offset: input.offset,
+            });
+        }
+        if (startDate && endDate && startDate < EFTS_FULLTEXT_FLOOR) {
+            // endDate ≥ 2001 (handled above) but startDate < 2001 → straddling. Reject
+            // with a split instruction; merged straddling output is a deferred follow-up.
+            throw ctx.fail('straddling_date_range', `The date range ${startDate}..${endDate} crosses 2001-01-01. Full-text search covers 2001-present; pre-2001 filings are served from the archives. Search the two eras separately: ${EFTS_FULLTEXT_FLOOR} onward, and before ${EFTS_FULLTEXT_FLOOR}.`, { ...ctx.recoveryFor('straddling_date_range') });
+        }
         // EFTS scores by relevance and exposes no sort param. When the caller wants
         // a date sort (the default) or entity filtering, we over-fetch the EFTS
         // window and reorder/slice client-side. Pure relevance mode keeps the
@@ -241,7 +564,6 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
         const wideFetch = entityCik !== undefined || input.sort !== 'relevance';
         const fetchFrom = wideFetch ? 0 : input.offset;
         const fetchSize = wideFetch ? 100 : input.limit;
-        const api = getEdgarApiService();
         const response = await api.searchFilings({
             query,
             forms: input.forms,
@@ -281,6 +603,7 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
                 file_description: hit._source.file_description ?? undefined,
                 sic: hit._source.sics?.[0] ?? undefined,
                 location: hit._source.biz_locations?.[0] ?? undefined,
+                source: 'efts',
             };
         });
         // Form distribution must reflect the same set as `total`.
@@ -289,14 +612,7 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
         // case, recompute from the post-filter `hits` to keep the counts consistent.
         let formDistribution;
         if (entityCik || input.forms?.length) {
-            const dist = {};
-            for (const hit of hits) {
-                const form = hit._source.form;
-                if (form)
-                    dist[form] = (dist[form] ?? 0) + 1;
-            }
-            if (Object.keys(dist).length > 0)
-                formDistribution = dist;
+            formDistribution = buildFormDistribution(hits.map((hit) => hit._source.form));
         }
         else if (response.aggregations?.form_filter?.buckets) {
             formDistribution = {};
@@ -325,6 +641,7 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
                     start_date: input.start_date,
                     end_date: input.end_date,
                     entity_cik: entityCik,
+                    source: 'efts',
                 },
                 truncated,
             });
@@ -339,21 +656,36 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
         });
         const effectiveQuery = entityCik
             ? `${query ? `${query} ` : ''}(entity scope: CIK ${entityCik})`
-            : query;
+            : query || (input.forms?.length ? `(browse: forms ${input.forms.join(', ')})` : '');
         ctx.enrich.echo(effectiveQuery);
         if (total === 0) {
-            // Genuine no-match — EFTS returned zero hits. Echo all active criteria.
-            const formsPart = input.forms?.length ? ` | Forms: ${input.forms.join(', ')}` : '';
-            const datePart = input.start_date && input.end_date
-                ? ` | Date: ${input.start_date} to ${input.end_date}`
-                : '';
-            ctx.enrich.notice(`No filings matched "${input.query}"${formsPart}${datePart}. Try broader search terms, remove form filters, or widen the date range.`);
+            // Genuine no-match — EFTS returned zero hits. Echo all active criteria; on the
+            // browse path (no query text) lead with the form/entity criteria instead of an
+            // empty quoted query.
+            const criteria = [];
+            if (query)
+                criteria.push(`"${query}"`);
+            if (entityCik)
+                criteria.push(`entity CIK ${entityCik}`);
+            if (input.forms?.length)
+                criteria.push(`forms [${input.forms.join(', ')}]`);
+            if (input.start_date && input.end_date) {
+                criteria.push(`dates ${input.start_date} to ${input.end_date}`);
+            }
+            const criteriaText = criteria.length > 0 ? criteria.join(', ') : 'the given criteria';
+            ctx.enrich.notice(`No filings matched ${criteriaText}. Broaden the query, remove the form filter, or widen the date range.`);
         }
         else if (results.length === 0 && wideFetch && input.offset >= hits.length) {
             // The offset exceeded the client-side window (wideFetch fetches 100 rows max).
             // There are results — the caller just paged past the available window. The
             // materialized dataframe holds the same window, so SQL paging reaches no further.
-            ctx.enrich.notice(`Offset (${input.offset}) exceeds the fetched window (${hits.length} rows — date sorts and entity targeting fetch a single window). ${total} filings matched: switch to sort=relevance for EDGAR-side pagination up to 10,000 results, or narrow the search with forms, dates, or entity targeting.`);
+            // Entity targeting forces wideFetch regardless of sort (see `wideFetch` above),
+            // so switching to sort=relevance does NOT unlock deeper EDGAR-side pagination on
+            // that path — only the non-entity path pages server-side via relevance.
+            const deeperPaging = entityCik
+                ? 'narrow the search with forms or dates, or query the full window via secedgar_dataframe_query'
+                : 'switch to sort=relevance for EDGAR-side pagination up to 10,000 results, or narrow the search with forms, dates, or entity targeting';
+            ctx.enrich.notice(`Offset (${input.offset}) exceeds the fetched window (${hits.length} rows — date sorts and entity targeting fetch a single window). ${total} filings matched: ${deeperPaging}.`);
         }
         else if (total > results.length) {
             ctx.enrich.truncated({ shown: results.length, cap: input.limit });
@@ -367,15 +699,21 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
         };
     },
     format: (result) => {
-        const exactness = result.total_is_exact ? 'exact' : 'capped at 10,000';
+        const source = result.results[0]?.source;
+        const exactness = result.total_is_exact
+            ? 'exact'
+            : source === 'submissions' || source === 'full-index'
+                ? 'partial — scan cap reached, more may exist'
+                : 'capped at 10,000';
         const lines = [`Found ${result.total} filings (${exactness})`];
         for (const r of result.results) {
             const period = r.period_ending ? ` (period: ${r.period_ending})` : '';
             const desc = r.file_description ? ` — ${r.file_description}` : '';
             const sic = r.sic ? ` | SIC ${r.sic}` : '';
             const loc = r.location ? ` | ${r.location}` : '';
+            const src = r.source ? ` | source: ${r.source}` : '';
             const ident = r.ticker ? `${r.ticker}, CIK ${r.cik}` : `CIK ${r.cik}`;
-            lines.push(`- ${r.form ?? 'N/A'} ${r.filing_date}${period} — ${r.company_name} (${ident})${sic}${loc}${desc} [${r.accession_number}]`);
+            lines.push(`- ${r.form ?? 'N/A'} ${r.filing_date}${period} — ${r.company_name} (${ident})${sic}${loc}${desc}${src} [${r.accession_number}]`);
         }
         if (result.form_distribution) {
             const dist = Object.entries(result.form_distribution)
@@ -385,7 +723,7 @@ export const searchFilingsTool = tool('secedgar_search_filings', {
         }
         if (result.dataset) {
             const truncatedNote = result.dataset.truncated
-                ? ' (truncated — more matches exist beyond the EFTS window)'
+                ? ' (truncated — more matches exist beyond the materialized set)'
                 : '';
             lines.push(`\nDataset: ${result.dataset.name} (${result.dataset.row_count} rows, expires ${result.dataset.expires_at})${truncatedNote} — query with secedgar_dataframe_query.`);
         }