edgar-search-mcp

Overview Schema Source Related Servers Discussions Admin

lookup_company

Read-only

Find SEC company_tickers.json rows that exactly match a CIK, ticker, or company title, and get the resolved 10-digit CIK or ambiguity status from strict, non-fuzzy matching.

Instructions

Find the rows of the SEC's company_tickers.json that equal a CIK, ticker or title.

A row matches only when its cik_str equals the query (digits), its ticker equals it (case aside) or its title equals it (case aside, runs of spaces read as one). There is no suffix, prefix or fuzzy matching. status is "resolved" (the matches share one CIK), "ambiguous" (they name several: choose one and use its CIK) or "not_found". Each match has the 10-digit cik, matched_on ("cik", "ticker" or "title"), record, the row as the SEC publishes it, and numbers_as_text, where in record a number is kept as its text (see the response contract); a company with several tickers has several rows. The feed lists current tickers and titles only, and a CIK that is not in it can still be given to every other tool directly.

Input Schema

Name	Required	Description	Default
`query`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.0.0Oct 29, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "envelope": {
+      "properties": {
+        "contract_version": {
+          "const": "1.0"
+        },
+        "representation": {
+          "enum": [
+            "source",
+            "source_records",
+            "parsed_source",
+            "transformed"
+          ]
+        },
+        "returned_at": {
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+          "type": "string"
+        },
+        "sources": {
+          "items": {
+            "$ref": "#/$defs/source"
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "unresolved": {
+          "items": {
+            "$ref": "#/$defs/unresolved"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "contract_version",
+        "representation",
+        "sources",
+        "returned_at"
+      ],
+      "type": "object"
+    },
+    "paths": {
+      "items": {
+        "items": {
+          "type": [
+            "string",
+            "integer"
+          ]
+        },
+        "type": "array"
+      },
+      "type": "array"
+    },
+    "source": {
+      "properties": {
+        "cache_hit": {
+          "type": "boolean"
+        },
+        "frozen": {
+          "type": "boolean"
+        },
+        "retrieved_at": {
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+          "type": "string"
+        },
+        "sha256": {
+          "pattern": "^[0-9a-f]{64}$",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "url": {
+          "pattern": "^https://(www|data|efts)\\.sec\\.gov/",
+          "type": "string"
+        }
+      },
+      "required": [
+        "url",
+        "retrieved_at",
+        "frozen",
+        "cache_hit"
+      ],
+      "type": "object"
+    },
+    "unresolved": {
+      "properties": {
+        "reason": {
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "reason"
+      ],
+      "type": "object"
+    }
+  },
+  "$id": "edgar://contract/1.0/lookup_company",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    {
+      "$ref": "#/$defs/envelope"
+    },
+    {
+      "properties": {
+        "matches": {
+          "items": {
+            "properties": {
+              "cik": {
+                "pattern": "^\\d{10}$",
+                "type": "string"
+              },
+              "matched_on": {
+                "enum": [
+                  "cik",
+                  "ticker",
+                  "title"
+                ]
+              },
+              "numbers_as_text": {
+                "$ref": "#/$defs/paths"
+              },
+              "record": {
+                "required": [
+                  "cik_str",
+                  "ticker",
+                  "title"
+                ],
+                "type": "object"
+              }
+            },
+            "required": [
+              "cik",
+              "matched_on",
+              "record",
+              "numbers_as_text"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "representation": {
+          "const": "source_records"
+        },
+        "status": {
+          "enum": [
+            "resolved",
+            "ambiguous",
+            "not_found"
+          ]
+        }
+      },
+      "required": [
+        "query",
+        "status",
+        "matches"
+      ]
+    }
+  ],
+  "type": "object"
+}

First observedv0.1.0Oct 29, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds substantial behavior beyond them: strict equality matching with case and whitespace normalization rules, the three-valued resolution status, the fact that a company with several tickers yields several rows, and the feed's coverage limitation. Minor misstep is the dangling reference to "the response contract" for `numbers_as_text`, which an agent cannot resolve from this text alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

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

Front-loaded with the core operation, and nearly every sentence carries genuine matching or status semantics. The enumeration of match fields (`cik`, `matched_on`, `record`, `numbers_as_text`) partly duplicates the output schema that already exists for this tool, and the mid-paragraph line breaks make it denser than necessary.

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

Completeness4/5

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

With an output schema present, the description need not detail return values, yet it still explains the meaning of `status` and `matched_on` — the parts an agent must reason about. Combined with the coverage caveat about current tickers only, an agent has enough to call this correctly and interpret results.

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 coverage is 0% — the single `query` string has no description at all — so the description must carry the load, and it does: it specifies that digits are matched against `cik_str`, and that ticker and title matching ignore case, with runs of spaces collapsed in titles. It stops short of stating precedence when a string could match more than one field, though the ambiguity status partially covers that outcome.

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 opening sentence states a specific verb and resource — find rows of the SEC's company_tickers.json — and defines the accepted key types (CIK, ticker, title). It implicitly separates this from the sibling tools, which consume a CIK rather than resolve one, and the closing note that a CIK not in the feed can still be passed to every other tool makes that relationship explicit.

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

Usage Guidelines4/5

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

Usage is well-framed: exact-match-only (no prefix/suffix/fuzzy), how to read each `status` value, and what to do on "ambiguous" (choose one and use its CIK). It also warns that the feed contains only current tickers and titles. What it lacks is an explicit statement of when to reach for this tool versus calling a sibling directly with a known CIK, though the closing sentence nearly says it.

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

Deploy Server