Skip to main content
Glama

secedgar-mcp-server

by io.github.cyanheads

Secedgar Dataframe Query

secedgar_dataframe_query
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sqlYesSingle-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.
previewNoRows 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_limitNoHard 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_asNoWhen 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

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe row cap that actually bound — `preview` when it is lower than `row_limit`, otherwise `row_limit`.
rowsNoMaterialized rows, bounded by `preview` / `row_limit`.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of rows returned inline.
noticeNoGuidance when the query returned no rows, or when the row cap withheld some.
columnsNoColumn names in projection order.
row_countNoTotal rows the query produced (may exceed `rows.length` when capped).
truncatedNoTrue when the result set held more rows than the row cap allowed through.
expires_atNoISO 8601 expiry timestamp for the newly registered dataframe, when applicable.
registered_asNoSet when `register_as` was supplied and the new dataframe was materialized.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed10 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "columns",
+      "row_count",
+      "rows"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / cap
      Added value: +{
+  "description": "The row cap that actually bound — `preview` when it is lower than `row_limit`, otherwise `row_limit`.",
+  "type": "number"
+}
    • addedOutput schema / properties / error
      Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: The DataCanvas service is not configured for this deployment `system_catalog_access`: The SQL query references a denied DuckDB system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*) `missing_table`: The SQL query references a df_<id> table that does not exist or has expired `invalid_sql`: The SQL statement contains a syntax or execution error not covered by a more specific reason `register_as_clash`: The register_as target name already exists on the canvas `non_select_statement`: The SQL is a non-SELECT statement (DROP, INSERT, UPDATE, DDL, etc.) — only read-only SELECTs run against dataframes Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "canvas_unavailable",
+            "system_catalog_access",
+            "missing_table",
+            "invalid_sql",
+            "register_as_clash",
+            "non_select_statement"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when the query returned no rows, or when results were capped."New value: +"Guidance when the query returned no rows, or when the row cap withheld some."
    • addedOutput schema / properties / shown
      Added value: +{
+  "description": "Number of rows returned inline.",
+  "type": "number"
+}
    • addedOutput schema / properties / truncated
      Added value: +{
+  "description": "True when the result set held more rows than the row cap allowed through.",
+  "type": "boolean"
+}
    • removedOutput schema / required
      Removed value: -[
-  "columns",
-  "row_count",
-  "rows"
-]
  2. Changed1 schema field changed
    • addedInput schema / properties / register_as / pattern
      Added value: +"^df_[A-Z0-9]{5}_[A-Z0-9]{5}$"
  3. Changed1 schema field changed
    • addedOutput schema / properties / notice
      Added value: +{
+  "description": "Guidance when the query returned no rows, or when results were capped.",
+  "type": "string"
+}
  4. Added

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description reinforces these and adds crucial behavior beyond annotations: rejected operations, denied catalogs, BIGINT serialization as JSON strings, TTL behavior for register_as. It does not mention default row_limit or response format, but the schema covers row_limit and the output schema exists. 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.

Conciseness5/5

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

Three sentences with high information density. The core restriction front-loads, and register_as appears at the end as a secondary concern. Parameter descriptions are concise and purposeful, each with a clear 'why.' No fluff or tautology.

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

Completeness5/5

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

For a complex query tool, the description covers safety (read-only), router (how to find dataframes), precision handling, and chaining behavior. With the output schema and rich input schema, an agent has everything needed to call correctly. The only minor omission is a timeout/performance note, but that's beyond reasonable expectation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds significant value: explains how to reference dataframes, introduces the BIGINT precision caveat and CAST advice, and clarifies when to lower preview. It doesn't restate schema fields but adds operational context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb ('Run'), an explicit resource ('single-statement SELECT against the canvas dataframes'), and names the three registering tools, instantly distinguishing this from sibling read tools like secedgar_dataframe_describe or search/fetch tools. It also specifies denial behavior, which sharpens the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states what is allowed (read-only SELECT) and what is forbidden (writes, DDL, catalogs). It names the alternative for listing dataframes (secedgar_dataframe_describe) and explains the purpose of register_as. This is thorough usage guidance for when to use the tool and when not to.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All secedgar-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.1/5.0
Disambiguation4/5

Most tools have clearly distinct purposes, with detailed descriptions that explicitly separate similar-sounding ones (e.g., secedgar_get_institutional_holdings vs secedgar_find_holders vs secedgar_get_beneficial_owners). The four ownership/holdings tools share a domain but are each tied to a different filing type and direction, so an agent reading carefully should not misselect.

Naming Consistency4/5

All tools share the secedgar_ prefix and mostly follow a get_/search_/dataframe_ convention. Minor deviations like fetch_frames, compare_companies, and find_holders break the otherwise consistent verb pattern, but the naming remains predictable and readable.

Tool Count4/5

16 tools is slightly above the typical well-scoped range, but the SEC EDGAR domain is broad enough that the count is defensible. Each tool covers a distinct data source or workflow, and the dataframe management pair adds necessary infrastructure rather than bloat.

Completeness4/5

The tool set covers company lookup, full-text filing search, XBRL concepts and frames, financial histories, comparisons, insider trades, institutional holdings, beneficial owners, fund holdings, and material events. Minor gaps exist — e.g., no explicit exhibit-content retrieval and no direct way to list all filings for a company beyond recent submissions — but core workflows are well covered.

Resources