secedgar-mcp-server
Server Details
Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/secedgar-mcp-server
- GitHub Stars
- 6
- Server Listing
- @cyanheads/secedgar-mcp-server
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.5/5 across 10 of 10 tools scored.
Each tool has a clearly distinct purpose: company search, filing retrieval, XBRL financial data, insider transactions, institutional holdings, concept search, and dataframe management. Descriptions explicitly differentiate boundaries, leaving no ambiguity.
All tools follow the 'secedgar_' prefix with a consistent verb_noun pattern (e.g., get_filing, search_filings, dataframe_describe). Variations like 'fetch_frames' vs 'get_' are still predictable and grouped by function.
10 tools is ideal for an SEC EDGAR server. It covers all major workflows—searching, retrieving filings, financials, insider/ institutional data, and XBRL analysis—without being overwhelming or sparse.
The tool set covers the full lifecycle: company discovery, filing retrieval (with pagination and sections), XBRL financial data (frames and historical), insider transactions (Form 4), institutional holdings (13F), and full-text search. Dataframe integration allows further analysis, leaving no obvious dead ends.
Available Tools
10 toolssecedgar_company_searchSecedgar Company SearchARead-onlyIdempotentInspect
Find companies and retrieve entity info with optional recent filings. Entry point for most EDGAR workflows — resolves tickers, names, or CIKs to entity details, with accession numbers in the result feeding secedgar_get_filing for document content.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Company ticker symbol (e.g., "AAPL", "VOO"), name (e.g., "Apple"), or CIK number (e.g., "320193"). Ticker is the fastest lookup and works for equities, ETFs, and mutual funds. Name search matches current and former names. | |
| form_types | No | Filter filings to specific form types (e.g., ["10-K", "10-Q", "8-K"]). Without this, returns all form types. | |
| filed_after | No | Only include filings filed on or after this date (YYYY-MM-DD). A date filter routes the scan into the older submissions archive pages, so it reaches filings that predate the ~1000-filing recent window (e.g. a company's 2005 10-K). | |
| filed_before | No | Only include filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after; together they bound the archive-page scan. | |
| filing_limit | No | Maximum number of filings to return in the inline list. | |
| include_filings | No | Include recent filings in the response. Set to false for entity-info-only lookups. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cik | Yes | Central Index Key, zero-padded to 10 digits. |
| sic | Yes | SIC industry code. |
| name | Yes | SEC-conformed company name. |
| notice | No | Guidance when include_filings=true but no filings matched the form_types filter. |
| dataset | No | Canvas dataframe holding the full filtered filing history (recent + archive pages), registered only when the scan reached beyond the recent window and the history exceeds filing_limit. Query the complete history — filings by form by year — with secedgar_dataframe_query; the inline `filings` list stays capped at filing_limit. |
| filings | No | Recent filings, filtered by form_types if specified. |
| tickers | Yes | Associated ticker symbols. |
| class_id | No | SEC fund class ID (e.g. "C000092055"). Present when the query resolved via a fund ticker (ETF or mutual fund). |
| exchanges | Yes | Exchanges where listed. |
| series_id | No | SEC fund series ID (e.g. "S000002839"). Present when the query resolved via a fund ticker (ETF or mutual fund). |
| total_filings | No | Total filings matching the filter across everything scanned (recent window + any archive pages), which may exceed filing_limit and the inline list. |
| fiscal_year_end | No | Fiscal year end (MM-DD format, e.g., "09-26"). Absent for filers SEC records no fiscal year end for (e.g. private or pre-IPO entities). |
| sic_description | Yes | Human-readable SIC description. |
| state_of_incorporation | No | State of incorporation (US two-letter code, e.g. "DE"). Omitted for some entities, including many foreign filers and individuals. |
| history_scanned_through | No | Oldest filing date reached by the scan (YYYY-MM-DD). Filings older than this were not examined: the recent window caps at ~1000 filings, and older filings live in archive pages fetched only when a date filter or an under-filled form filter requires them. Absent when no filings were scanned. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare read-only, open-world, idempotent. Description adds behavioral details like optional filings, resolving identifiers, and that date filters route to archive pages for older filings. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence that is front-loaded with key information. It is concise but could be slightly more structured, yet it effectively conveys the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high schema coverage, annotations, and output schema presence, the description provides sufficient context: it explains the tool's role, how it integrates with other tools (secedgar_get_filing), and the behavior of date parameters for archive access.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed parameter explanations. The main description adds overall workflow context but does not significantly enhance parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds companies and retrieves entity info with optional filings. It specifies it is the entry point for EDGAR workflows and resolves tickers, names, or CIKs, distinguishing it from sibling tools like secedgar_get_filing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description positions this as the entry point and mentions that accession numbers feed into secedgar_get_filing, implying usage context. However, it lacks explicit 'when not to use' or alternatives, but the schema parameter descriptions provide guidance on query types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
secedgar_dataframe_describeSecedgar Dataframe DescribeARead-onlyIdempotentInspect
List dataframes (df_XXXXX_XXXXX) materialized by secedgar_fetch_frames, secedgar_search_filings, secedgar_get_financials, secedgar_get_insider_transactions, and secedgar_get_institutional_holdings. Each entry surfaces source tool, query parameters, creation/expiry timestamps, row count, column schema, and whether the dataframe is truncated relative to the upstream source.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional table name (df_XXXXX_XXXXX) to describe a single dataframe. Omit to list all dataframes. |
Output Schema
| Name | Required | Description |
|---|---|---|
| dataframes | Yes | Active dataframes for this tenant, newest first. Empty when none are registered. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent. The description adds valuable behavioral details (source tool, timestamps, truncation info) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main action, each sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema covers return values, the description fully covers the tool's role, listing all source tools and the metadata fields shown.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description correctly notes the parameter is optional. No additional semantic value beyond the schema is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: listing dataframes (df_XXXXX_XXXXX) from multiple related tools, distinguishing it from siblings like secedgar_dataframe_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for listing metadata, but lacks explicit guidance on when to use this vs alternatives like secedgar_dataframe_query. No exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
secedgar_dataframe_querySecedgar Dataframe QueryARead-onlyIdempotentInspect
Run a single-statement SELECT against the canvas dataframes registered by secedgar_fetch_frames, secedgar_search_filings, and secedgar_get_financials. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied — list dataframes via secedgar_dataframe_describe. Optional register_as chains the result as a new dataframe with a fresh TTL.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | Single-statement SELECT against df_<id> tables on the shared canvas. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Reference dataframes by the names returned in fetch/search responses or listed by secedgar_dataframe_describe. BIGINT columns (e.g., XBRL `value`, COUNT/SUM results) serialize as JSON strings to preserve precision past 2^53 — CAST(col AS DOUBLE) in projections for inline arithmetic. | |
| preview | No | Rows to include in the immediate response. Defaults to the row limit. Set lower (e.g., 50) when chaining via register_as and only a sample is needed inline. | |
| row_limit | No | Hard cap on rows materialized in the response. Default 1000, max 10000. The full result lives on-canvas under register_as when provided — do not raise this to keep large results. | |
| register_as | No | When set, persist the result as a new dataframe under this name (must match df_XXXXX_XXXXX shape, or pass a fresh df_<id> generated by the agent). Fresh TTL window — not inherited from the parents in the SELECT. Use to chain analyses without re-running the source SQL. |
Output Schema
| Name | Required | Description |
|---|---|---|
| rows | Yes | Materialized rows, bounded by `preview` / `row_limit`. |
| notice | No | Guidance when the query returned no rows, or when results were capped. |
| columns | Yes | Column names in projection order. |
| row_count | Yes | Total rows the query produced (may exceed `rows.length` when capped). |
| expires_at | No | ISO 8601 expiry timestamp for the newly registered dataframe, when applicable. |
| registered_as | No | Set when `register_as` was supplied and the new dataframe was materialized. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint and idempotentHint annotations, the description adds detailed behavioral traits: rejected statements, system catalog denial, BIGINT serialization, and TTL behavior for register_as. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and informative, though slightly verbose. Each sentence adds value, but could be tightened slightly without loss of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of querying multiple dataframes with chaining, type behaviors, and constraints, the description covers all essential aspects. No output schema exists, but the return behavior is standard for a query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description enriches each parameter with usage context: sql explains BIGINT serialization and SQL dialect; preview explains chaining; row_limit explains hard cap and canvas persistence; register_as explains naming pattern and TTL. This goes beyond baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs SELECT queries against canvas dataframes, distinguishing it from sibling tools like secedgar_fetch_frames and secedgar_search_filings which fetch data. The verb 'Run a single-statement SELECT' is specific and the resource is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists rejected operations (writes, DDL, DROP, etc.) and mentions optional register_as for chaining. It provides clear context on when to use this tool, though it doesn't explicitly contrast with siblings; however, the purpose is distinct enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
secedgar_fetch_framesSecedgar Fetch FramesARead-onlyIdempotentInspect
Fetch SEC XBRL frames for one concept × one period across all reporting companies. Inline response returns the top N ranked companies; the full frames response (all reporters) is materialized as df_ when a canvas is available, queryable via secedgar_dataframe_query. Accepts friendly names like "revenue" or "assets" (discover via secedgar_search_concepts) or raw XBRL tags. One call hits one XBRL tag — when a friendly name maps to multiple same-meaning tags, the response's unqueried_tags lists the others; call again per tag and UNION/COALESCE in SQL with an analysis-specific priority (e.g. SalesRevenueGoodsNet is goods-only). The response's related_tags separately flags alternate-DEFINITION tags a meaningful share of filers use as their primary line (e.g. cash incl. restricted cash, equity incl. noncontrolling interest) — a whole-universe screen on the base tag silently omits those filers; query them separately, but do not blindly union (the semantics differ). Response includes value_distribution and period_end_range to flag XBRL scale-factor anomalies and fiscal-year mixing.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort direction. "desc" for highest values first (typical for revenue, assets). "asc" for lowest values. | desc |
| unit | No | Unit of measure. Use "USD-per-shares" (or equivalently "USD/shares") for EPS, "shares" for share counts, "pure" for ratios. Ignored when concept resolves to a friendly name with a known unit. | USD |
| limit | No | Number of companies to return. | |
| period | Yes | Calendar period. Use duration periods (no I suffix) for income/cash-flow items: "CY2023" (full year), "CY2024Q2" (single quarter). Use instant periods (I suffix) for balance-sheet items: "CY2023Q4I" (snapshot at Q4 close). | |
| concept | Yes | Financial concept — same friendly names as secedgar_get_financials (e.g., "revenue", "assets", "eps_basic") or raw XBRL tag. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit cap applied. |
| data | Yes | Ranked companies for this metric. |
| unit | Yes | Unit of measure used for the lookup (always normalized to dashed form, e.g. "USD-per-shares"). |
| label | Yes | Human-readable concept label. |
| shown | No | Number of companies shown inline. |
| period | Yes | Calendar period the data was fetched for, echoed from input. |
| caveats | Yes | Data-completeness warnings specific to this query. Currently populated for duration periods 'CY####Q[1-4]', where SEC XBRL omits filers' fiscal Q4 (reported only as the 10-K residual) — affected filers are silently absent from the frame. Empty for annual ('CY####') and instant ('CY####Q#I') periods, where the underlying facts exist and the frame is complete. |
| concept | Yes | XBRL tag the data was actually fetched against (after resolving any friendly name). |
| dataset | No | Canvas dataframe handle holding the full frames response. Absent when canvas is unavailable or materialization failed. |
| truncated | No | True when the inline data[] was capped by limit. |
| related_tags | Yes | Alternate-DEFINITION XBRL tags (distinct from same-meaning `unqueried_tags`) that a meaningful share of filers use as their primary line for this metric — e.g. `cash` filers reporting `CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents` (incl. restricted cash), `equity` filers reporting `StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest` (incl. noncontrolling interest). These filers are NOT in `data` or the dataframe, so a whole-universe screen on the base tag silently under-counts. To recover them, run a separate fetch_frames against the alternate tag — do NOT blindly UNION (definitions differ; you would mix or double-count). Empty when the concept has no known high-coverage alternate. |
| unqueried_tags | Yes | Other same-meaning XBRL tags in the friendly-name mapping that this call did NOT query (historical/variant spellings of the same metric). Empty for raw tags or single-tag concepts — for alternate-DEFINITION tags some filers use instead, see `related_tags`. For "revenue" this typically lists `Revenues`, `SalesRevenueNet`, `SalesRevenueGoodsNet` — filers reporting under legacy variants are absent from `data`; call again per tag and UNION/COALESCE in SQL to recover them. |
| total_companies | Yes | Total companies reporting this metric for this period. |
| period_end_range | Yes | Range of period_end dates across the frame. SEC normalizes to calendar periods but filers report against their own fiscal year-ends, so a "CY2023" duration frame can contain period_ends from 2023-01-31 (January-FY filers like Walmart) to 2024-12-31 (calendar-FY filers reported late). Wide ranges mean cross-comparison mixes fiscal periods. |
| value_distribution | Yes | Distribution stats across the full frame, computed during materialization. Use `max_to_p95_ratio` as the primary outlier signal — it catches scale-factor anomalies even when median is 0 or negative. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral details: inline vs full response, friendly name resolution, unqueried_tags, related_tags, scale-factor anomalies, and fiscal-year mixing. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy but every sentence adds substantive information. It is front-loaded with the core purpose. Could be slightly more structured, but remains efficient given the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, an output schema, and annotations, the description is highly complete. It covers purpose, usage, parameter semantics, behavioral details, and output expectations. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds valuable context beyond schema: for 'concept' it references secedgar_get_financials, for 'period' it explains duration vs instant with examples, for 'limit' states count, and for 'sort' and 'unit' gives usage tips. Significantly enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch', the resource 'SEC XBRL frames', and the scope 'one concept × one period across all reporting companies'. It differentiates from sibling tools by referencing secedgar_dataframe_query and secedgar_search_concepts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (one concept, one period), when not (friendly names may map to multiple tags requiring separate calls), and alternatives (secedgar_dataframe_query for full response, secedgar_search_concepts for discovery). Warns about related_tags and unqueried_tags semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
secedgar_get_filingSecedgar Get FilingARead-onlyIdempotentInspect
Fetch a specific filing's metadata and document content by accession number. Returns the primary document as readable text. Use offset/next_offset for multi-page access to large filings (10-K, S-1 can exceed 1M chars): pass the next_offset from a truncated response to read the next page. Use section to jump directly to a heading (e.g. 'risk factors', 'item 7') without needing an offset.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | No | Company CIK, digits only (resolve via secedgar_company_search if you have a ticker or name). Optional but recommended — speeds up archive lookup. If omitted, likely filing CIKs are inferred from SEC search metadata and archive paths. | |
| offset | No | Character offset into the extracted document text. Pass next_offset from a truncated response to continue reading the next page. Default 0 reads from the beginning. | |
| section | No | Jump to a named section by case-insensitive substring match against detected headings (e.g. 'risk factors', 'item 7', 'certain relationships'). Takes precedence over offset when both are provided. On a miss, the error message includes the detected outline so you can pick the correct heading. | |
| document | No | Specific document filename within the filing (e.g., "ex-21.htm" for subsidiaries list). Default: the primary document. Available documents listed in the response metadata. | |
| include_xbrl | No | Include XBRL viewer artifacts and machine-readable taxonomy files (R*.htm fragments, *_cal/_def/_lab/_pre.xml linkbases, *_htm.xml inline instance, *.xsd schemas, MetaLinks.json, FilingSummary.xml, Show.js, report.css, *-xbrl.zip, Financial_Report.xlsx, EX-101.* technical exhibits) under documents.xbrl. Off by default — these dominate filing indexes (~100 entries on a typical 10-K) and are rarely relevant when reading filing content. | |
| content_limit | No | Maximum characters of document text to return per page. 10-K filings can exceed 500,000 characters; S-1/A can exceed 1,000,000. Default 50,000 captures ~12,000 words (typically business overview, risk factors, and MD&A). Increase to 200,000 for full financial statements, or decrease for quick summaries. Use offset or section for subsequent pages. | |
| accession_number | Yes | Filing accession number in either format: "0000320193-23-000106" (dashes) or "000032019323000106" (no dashes). Obtained from secedgar_company_search or secedgar_search_filings results. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cik | Yes | Filing entity CIK, zero-padded to 10 digits. |
| form | No | Form type (e.g., "10-K", "10-Q"). Absent for filings older than the last ~1,000 the company has filed (SEC does not surface metadata for those without a separate fetch). |
| content | Yes | Document text content for this page window. |
| outline | No | Document outline — detected headings with their character offsets. Present on the first page of a truncated response (offset=0, no section). Use a heading offset as offset, or pass heading text as section, to jump to that section. |
| documents | Yes | Filing documents grouped by category. Names from any list are valid values for the document input. XBRL viewer artifacts are suppressed by default; setting include_xbrl=true surfaces them under the xbrl bucket. |
| filing_url | Yes | Direct URL to the filing on SEC.gov. |
| filing_date | No | Date the filing was submitted (YYYY-MM-DD). Absent under the same conditions as form. |
| next_offset | No | Character offset to pass as offset on the next call to continue reading. Only present when the response was truncated. Calling agents should follow this until content_truncated is false. |
| company_name | No | Filing entity name. Absent if the CIK did not resolve to a known entity. |
| period_ending | No | Period the filing reports on (YYYY-MM-DD). Absent under the same conditions as form. |
| accession_number | Yes | Filing accession number, normalized to dash format. |
| primary_document | Yes | Filename of the filing's actual primary document (e.g., the 10-K HTML file). |
| content_truncated | Yes | True if content was truncated at content_limit. |
| requested_document | No | Filename of the specific document requested via the document param. Only present when document differs from primary_document. |
| content_total_length | Yes | Full document length before any truncation. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description discloses behavior: it returns primary document as text, truncates large filings (mentions 10-K, S-1), explains pagination with offset/next_offset, and clarifies that include_xbrl is off by default to avoid clutter. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two concise sentences upfront, then parameter-level guidance. Every sentence contributes useful information without redundancy. It uses clear, actionable language like 'pass the next_offset' and 'takes precedence over offset'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (not shown), the description covers all key aspects: pagination, section navigation, error recovery, and parameter defaults. It addresses edge cases like large filings and missing sections, making it complete for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds context beyond schema definitions, e.g., explaining why include_xbrl defaults to false ('dominant filing indexes and rarely relevant'), and how section error returns an outline. This adds practical value for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'Fetch a specific filing's metadata and document content by accession number', using a specific verb and resource. It distinguishes itself from sibling tools like secedgar_search_filings (which searches for filings) and secedgar_company_search (which resolves identifiers) by focusing on retrieving content for a known filing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidelines: 'Use offset/next_offset for multi-page access to large filings' and 'Use section to jump directly to a heading'. It also references a sibling tool in the cik parameter description ('resolve via secedgar_company_search'), helping the agent decide when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
secedgar_get_financialsSecedgar Get FinancialsARead-onlyIdempotentInspect
Get historical XBRL financial data for a company. Accepts friendly concept names (e.g., "revenue", "net_income", "assets") or raw XBRL tags. Discover available friendly names with secedgar_search_concepts. Handles historical tag changes and deduplicates data automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Cap the inline data[] to the most-recent N periods (the series is newest-first). The full series is always registered to the dataframe, so older periods stay queryable via secedgar_dataframe_query. Omit to return every period inline. | |
| company | Yes | Ticker symbol (e.g., "AAPL") or CIK number. Ticker is preferred. | |
| concept | Yes | Financial concept — friendly name (e.g., "revenue", "net_income", "assets", "eps_diluted") or raw XBRL tag (e.g., "AccountsPayableCurrent"). Friendly names auto-resolve to the correct XBRL tags and handle historical tag changes. | |
| taxonomy | No | XBRL taxonomy. us-gaap for US companies, ifrs-full for foreign filers, dei for entity info (shares outstanding). | us-gaap |
| period_type | No | Filter to annual (FY) or quarterly (Q1-Q4) data. "all" returns both. When omitted, defaults to "annual"; instant (balance-sheet) concepts automatically fall back to returning the full series on the first call when the annual filter yields nothing (#48). |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit cap applied. |
| cik | Yes | Resolved CIK, zero-padded to 10 digits. |
| data | Yes | Deduplicated time series, newest first. |
| unit | Yes | Unit of measure (e.g., "USD", "shares", "USD/shares"). |
| label | Yes | Human-readable label for the concept. |
| shown | No | Number of periods shown inline. |
| company | Yes | Resolved entity name (SEC-conformed). |
| concept | Yes | XBRL tag name used. |
| dataset | No | Canvas dataframe handle holding the same time series. Use for cross-company JOINs via secedgar_dataframe_query. The source-filing fiscal keys are materialized as source_filing_fy/source_filing_fp — order, group, and window by period_end, not by those columns. Absent when canvas is unavailable. |
| truncated | No | True when the inline data[] was capped by limit. |
| tags_tried | No | XBRL tags that were attempted (shown when using friendly names that map to multiple tags). |
| description | No | XBRL taxonomy description for this concept. Often absent for company-extension tags or older concepts. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, and idempotentHint. The description adds significant behavioral details beyond these: it mentions automatic handling of historical tag changes, deduplication, and the limit parameter's effect on inline data while preserving full series for dataframe queries. No contradictions with annotations are present, and the description enriches the agent's understanding of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence. It contains four sentences, each providing essential information without fluff. It efficiently covers purpose, alternatives, behavior, and parameter details. No redundant or unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (all described in schema), an output schema (so return values are covered), and annotations providing safety and idempotency info, the description provides sufficient context. It explains how to use friendly names, handles edge cases (historical changes, deduplication), and points to sibling tools for further operations (dataframe query). This makes the tool usage complete and well-integrated with other tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by providing examples of friendly concept names (e.g., 'revenue', 'net_income') and explaining that they auto-resolve to XBRL tags. It also clarifies the behavior of the 'limit' parameter (capping inline data but preserving full series). This adds meaningful context beyond the schema descriptions, justifying a score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get historical XBRL financial data for a company', providing a specific verb ('get'), resource ('XBRL financial data'), and scope ('historical'). It distinguishes itself from sibling tools by mentioning 'secedgar_search_concepts' for concept discovery and implicitly differs from other data retrieval tools (e.g., secedgar_get_filing, secedgar_get_insider_transactions). This is a clear and unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (to get historical financial data) and when to use an alternative ('Discover available friendly names with secedgar_search_concepts'). It also describes the tool's automatic handling of historical tag changes and deduplication, giving context for expected behavior. However, it does not explicitly exclude usage for other data types (e.g., insider transactions), leaving room for ambiguity. This is good but not perfect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
secedgar_get_insider_transactionsGet Insider TransactionsARead-onlyIdempotentInspect
Fetch Form 4 insider transactions (purchases, sales, grants, exercises) for a company by parsing SEC EDGAR ownership XML. Returns the reporting person, their relationship to the issuer, transaction date, type, shares traded (absolute magnitude), direction (acquire/dispose), price per share, and shares owned after the transaction. Covers nonDerivative transactions (open-market buys/sells, gifts) and derivative transactions (option exercises, RSU vests). When a canvas is available, the full set of transactions parsed from the scanned recent filings is materialized as df_ (the inline list is a preview capped at limit) — query it with secedgar_dataframe_query to aggregate net buy/sell by insider: SUM(CASE WHEN direction='dispose' THEN -shares_traded ELSE shares_traded END). Use secedgar_search_filings with forms=["4"] for broader date-range queries or to search across all companies.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of transactions to return across all Form 4 filings fetched. Filings are scanned newest-first. Default 20. | |
| ticker_or_cik | Yes | Company ticker symbol (e.g., "AAPL") or 10-digit CIK number (e.g., "0000320193"). The issuer, not the reporting person. | |
| transaction_type | No | Filter by direction. "purchase" = open-market buys (code P). "sale" = open-market sells (code S). "all" includes grants, awards, exercises, gifts, and other coded transaction types as well. | all |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit cap applied. |
| shown | No | Number of transactions shown inline. |
| notice | No | Guidance when results are empty after filtering — explains the filter applied and suggests alternatives. |
| dataset | No | Canvas dataframe holding the full parsed transaction set from the scanned filings (the inline transactions[] is a preview capped at limit). Each row carries the issuer (issuer_cik, issuer_ticker) plus the transaction fields, so it aggregates net buy/sell by insider and joins across issuers. Query with secedgar_dataframe_query. Absent when canvas is unavailable or no transactions were parsed. |
| truncated | No | True when the inline transactions[] was capped by limit. |
| issuer_cik | Yes | Issuer CIK, zero-padded to 10 digits. |
| issuer_name | Yes | Issuer entity name (SEC-conformed). |
| transactions | Yes | Insider transactions, newest filing first. Preview capped at `limit` — the full scanned set lives on the canvas dataframe (see `dataset`). |
| issuer_ticker | No | Issuer ticker symbol when available. |
| filings_scanned | Yes | Number of Form 4 filings scanned to produce the result. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that scans recent filings, materializes full dataset as df_<id> when canvas is available, and preview is capped at limit. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Efficiently structured: main purpose first, then returned fields, canvas handling, and sibling reference. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (3 params, output schema present, sibling tools), description covers behavior, canvas integration, and alternative usage comprehensively. Output schema handles return value documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: explains limit scans newest-first across filings, differentiates transaction_type options (purchase/sale/all includes grants, awards, exercises, gifts). Schema coverage is 100%, and description enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it fetches Form 4 insider transactions, specifies data returned (reporting person, relationship, date, type, shares, direction, price, after-transaction shares), and distinguishes from siblings by mentioning alternative tools for broader queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance to use secedgar_search_filings for broader date-range queries or cross-company searches. Also describes canvas integration for aggregation, but does not explicitly state when NOT to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
secedgar_get_institutional_holdingsGet Institutional HoldingsARead-onlyIdempotentInspect
Fetch 13F-HR quarterly institutional holdings by parsing the SEC EDGAR information table XML. ticker_or_cik is the institutional filer — its 10-digit CIK (e.g. 0000102909), or an entity name resolved through EDGAR entity search — and the tool returns what that institution holds. A name that matches several EDGAR filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK, rather than guessing. It does not do reverse lookup from a portfolio company to its institutional holders (EDGAR has no issuer-to-13F index); for issuer-side questions, use secedgar_search_filings with forms=["13F-HR"]. The 13F information table lists each position: issuer name, CUSIP, shares held, market value (in whole USD), and put/call designation for options. Sub-lines for the same security are consolidated into distinct positions sorted by value by default (set consolidate=false for raw filing rows). The full parsed holdings set is materialized as df_ when a canvas is available — the inline holdings list is a preview capped at limit — so query it with secedgar_dataframe_query to aggregate the whole filing or self-join across quarters on cusip + reporting_period. Institutions with less than $100M in 13(f) securities are exempt and may not file. Use secedgar_search_filings with forms=["13F-HR"] for broader search.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of holdings rows to return. 13F filings from large institutions can contain thousands of positions. Default 20. | |
| quarter | No | Reporting quarter to target, in "YYYY-QN" format (e.g., "2025-Q4"). When omitted, returns the most recent 13F-HR available. Quarters map to the filing window: Q4 2025 = filings submitted roughly Jan–Mar 2026. | |
| consolidate | No | When true (default), info-table sub-lines for the same security (CUSIP + class + put/call) are summed into one position and results are sorted by market value descending, so `limit` returns the largest distinct holdings. Set false to return raw information-table rows in filing order (one per investment-discretion/manager sub-line), preserving investment_discretion. | |
| ticker_or_cik | Yes | The institutional filer whose 13F to fetch — a 10-digit CIK (e.g. "0000102909" for VANGUARD GROUP INC, the most reliable form) or an entity name. Names resolve through EDGAR entity search, which covers institutional managers absent from the ticker file; a name matching several filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK. This is NOT the portfolio company — passing an issuer ticker like "AAPL" finds that operating company's own filings (it files no 13F), not who holds it. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit cap applied. |
| shown | No | Number of holdings shown inline. |
| notice | No | Guidance when no filings were found or the result set is empty — suggests alternatives. |
| dataset | No | Canvas dataframe holding every parsed position from this 13F filing (the inline holdings[] is a preview capped at limit). Each row carries the filer metadata (filer_cik, filer_name, reporting_period, filing_date, accession_number) plus the position fields, so it self-joins across quarters/filers on cusip + reporting_period. Reflects the consolidate setting (consolidated positions when true, raw info-table sub-lines with investment_discretion when false). Query with secedgar_dataframe_query. Absent when canvas is unavailable or the filing had no holdings. |
| holdings | Yes | Holdings truncated to limit — consolidated positions sorted by market value when consolidate=true, else raw information-table rows in filing order. |
| filer_cik | Yes | CIK of the 13F filer, zero-padded to 10 digits. |
| truncated | No | True when the inline holdings[] was capped by limit. |
| filer_name | Yes | Name of the institutional filer (the 13F submitter). |
| filing_date | Yes | Date the 13F was submitted (YYYY-MM-DD). |
| total_positions | No | Number of distinct positions after consolidating info-table sub-lines, before the limit. Present only when consolidate=true. |
| accession_number | Yes | Accession number for this 13F-HR filing — pass to secedgar_get_filing for the full document. |
| reporting_period | No | The calendar-quarter end date this 13F covers (YYYY-MM-DD), from the filing cover page. Absent if not surfaced in the filing. |
| total_holdings_in_filing | Yes | Total number of raw information-table rows in this filing, before consolidation and the limit. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint. The description adds context beyond annotations: name resolution returns candidates if ambiguous, consolidation default behavior, materialization as df_<id> in canvas, and the limit preview cap. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthier than typical but each sentence adds value. It is front-loaded with purpose and usage, then covers parameters and behavioral details. Could be slightly more concise but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (CIK resolution, consolidation, canvas integration, output schema), the description is very complete. It covers input, behavior, output, limitations, and integration with sibling tools. The output schema exists, so return values are documented there.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The description adds extra meaning: for ticker_or_cik clarifies it's the institutional filer not portfolio company; for quarter maps to filing window; for consolidate explains sorting; for limit notes large institutions can have thousands of positions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches 13F-HR quarterly institutional holdings by parsing SEC EDGAR XML. It distinguishes from sibling tools by noting secedgar_search_filings for issuer-side questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (for institutional holdings) and when not (for reverse lookup or issuer-side), and provides specific alternative: use secedgar_search_filings with forms=['13F-HR']. Also notes that institutions with less than $100M may not file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
secedgar_search_conceptsSecedgar Search ConceptsARead-onlyIdempotentInspect
Search supported XBRL financial concepts by keyword, statement group, or taxonomy. Use before secedgar_get_financials or secedgar_fetch_frames to discover the right friendly name, or pass a raw XBRL tag (e.g., "NetIncomeLoss") to reverse-lookup which friendly names map to it. Empty search with no filters returns the full catalog.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | Filter to a single financial statement group. income_statement covers P&L items; balance_sheet covers position items (use instant periods in secedgar_fetch_frames); cash_flow covers CF statement items; per_share covers EPS; entity_info covers DEI items like shares outstanding. | |
| search | No | Case-insensitive substring matched against friendly name, label, and XBRL tags. Examples: "cash" finds cash and operating_cash_flow; "earnings" finds eps_basic and eps_diluted; "NetIncomeLoss" reverse-maps to net_income. Omit to list all concepts. | |
| taxonomy | No | Filter to a single XBRL taxonomy. us-gaap for US filers, ifrs-full for foreign filers, dei for entity info. |
Output Schema
| Name | Required | Description |
|---|---|---|
| total | Yes | Number of concepts matching the filters. |
| notice | No | Guidance when no concepts matched — echoes the search term and suggests alternatives. |
| concepts | Yes | Matching concepts, ordered by group then alphabetical by name. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description's behavioral disclosure is minimal. It adds context about reverse-lookup and empty search returning full catalog, which is useful but not extensive. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and immediately provides usage context. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (3 optional params, output schema present, good annotations), the description covers the purpose, usage, special behaviors (reverse-lookup, empty catalog), and sufficient context. Output schema handles return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each parameter. The description adds some value by explaining the reverse-lookup use case for the search parameter and the purpose of group, but largely overlaps with schema descriptions. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches XBRL concepts by keyword, group, or taxonomy, and distinguishes itself from sibling tools by mentioning it is used before secedgar_get_financials and secedgar_fetch_frames. It also specifies a unique reverse-lookup feature, making the purpose highly specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool before two specific siblings to discover friendly names, providing clear positive guidance. However, it does not include explicit when-not scenarios or alternatives beyond the mentioned siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
secedgar_search_filingsSecedgar Search FilingsARead-onlyIdempotentInspect
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).
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | 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. | filing_date_desc |
| forms | No | Filter to specific form types (e.g., ["10-K", "10-Q", "8-K"]). Without this, searches all form types. Note: "10-K" also matches amendments filed as 10-K/A. Ownership forms (3, 4, 5) are indexed by the reporting person (e.g., "LEVINSON ARTHUR D"), not the issuer — rows carry no transaction code, share count, or price. Use secedgar_get_insider_transactions to retrieve parsed ownership XML with person, relationship, transaction code, shares, and price. | |
| limit | No | Results per page. Max 100. | |
| query | No | 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. | |
| offset | No | Pagination offset. For sort=relevance, EDGAR pages server-side up to its 10,000-result cap. For date sorts (the default) and entity targeting, the tool fetches a single 100-row window and slices it client-side — offsets at or past the window return nothing; switch to sort=relevance for deep pagination, or narrow the search (forms, dates, entity targeting). | |
| end_date | No | End of date range (YYYY-MM-DD). Both start_date and end_date must be provided for date filtering. | |
| start_date | No | Start of date range (YYYY-MM-DD). Both start_date and end_date must be provided for date filtering. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit cap applied. |
| shown | No | Number of results shown inline. |
| total | Yes | 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). |
| notice | No | Guidance when no results were returned — echoes the query and suggests how to broaden. |
| dataset | No | 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. |
| results | Yes | Matching filings. |
| truncated | No | True when results were capped by limit. |
| effectiveQuery | Yes | The query as executed against EDGAR (ticker/cik: tokens resolved to entity names). |
| total_is_exact | Yes | 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. |
| form_distribution | No | Count of results by form type. Helps narrow follow-up searches. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds context about index coverage (2001-present full-text, pre-2001 archive behavior) and the requirement of entity targeting for pre-2001 full-text. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose. It includes the most important details (date range, search syntax, entity targeting) without extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, date range, pre-2001 nuances, sort modes), the description provides a high-level overview. The detailed schema descriptions fill in the gaps (e.g., offset behavior, sort reordering). Combined with the output schema, the definition is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The main description adds minimal extra beyond schema (e.g., entity targeting examples). The schema descriptions themselves are very thorough, covering sort behavior, offset limits, and date constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search EDGAR filings since 1993' with specific capabilities (full-text, entity targeting, date ranges). It clearly differentiates from siblings like secedgar_get_filing (retrieve specific filing) and secedgar_company_search by focusing on filing search and providing details on pre-2001 handling and search syntax.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives, but the schema parameter descriptions for 'forms' and 'query' provide guidance: forms mentions using secedgar_get_insider_transactions for ownership filings, and query explains when to omit query for browsing. The main description lacks explicit exclusions, but the detailed schemas compensate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!
Your Connectors
Sign in to create a connector for this server.