SEC EDGAR as clean JSON: Form 4 insider trades, 8-Ks, 13F holdings, 13D/G >5% stakes, fundamentals.
Scored across 15 tools
Most tools map to distinct SEC data types (insider trades, 13F holdings, 13D/G, Form D, subsidiaries), but get_company/resolve_entity both resolve basic entity identity and get_xbrl appears to superset get_fundamentals, creating boundary ambiguity. Descriptions clarify usage somewhat, but an agent could easily select the wrong one.
The dominant pattern is get_<data type> in snake_case, which is consistent and predictable. resolve_entity and search_filings break the get_ prefix but still follow a clear verb_noun structure, so the deviation is minor.
Fifteen tools is on the upper edge of the ideal range and is reasonable for a comprehensive SEC/EDGAR data API. A couple of overlapping tools could be consolidated, but the count is not bloated.
The surface covers company identity, filing history, full-text search, 8-K events, XBRL fundamentals, narrative sections, shares, ratios, insiders, institutional holdings, activist stakes, and private offering data. No obvious dead ends or missing SEC data categories for the stated purpose.
Schedule 13D/13G filings, the disclosure anyone crossing 5% of a company's voting stock must make. A 13D signals possible activist intent; a 13G is a passive large holder. Each record has the issuer, CUSIP, reporting person(s), and exact percent of class. Pass identifier='latest' for the market-wide feed of new >5% stakes, or a ticker for the stakes indexed on that company.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of filings, 1-100 (default 40). | |
| identifier | Yes | 'latest' for the market-wide >5% feed, or a US ticker (e.g. 'AAPL') for stakes indexed on that company. | |
| min_percent | No | For 'latest': minimum percent of class (default 0). | |
| activist_only | No | For 'latest': keep only 13D (activist-intent) filings (default false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds value by explaining the meaning of the filings (13D vs 13G) and the exact fields returned (issuer, CUSIP, reporting person(s), percent of class). This contextual disclosure goes beyond annotations and helps the agent understand the tool's output semantics without an output schema.
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 four sentences long but each sentence earns its place: it defines 13D/13G, clarifies the threshold, lists the record fields, and explains the identifier modes. It is front-loaded with purpose and avoids filler, though the first two sentences could arguably be condensed. Overall it is efficient and well-structured for an agent scanning for key information.
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 no output schema, the description provides a useful outline of return fields (issuer, CUSIP, reporting person(s), percent). It also covers the two invocation modes thoroughly. It does not mention pagination, error behavior, or edge cases, but for a read-only, idempotent tool with a single required parameter, these are less critical. The description is sufficient for correct invocation and basic outcome expectations.
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?
All four parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds meaningful depth to the required 'identifier' parameter by explaining the two distinct value modes ('latest' vs ticker) and their purposes, which the schema merely hints at. This elevates the semantic clarity of the most important parameter beyond what the schema alone provides.
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 names a specific resource (13D/13G activist stakes) and a clear action (get/fetch), going beyond the name to explain the domain context (5% threshold, 13D vs 13G). It also distinguishes two modes of operation (latest vs ticker) that align with the identifier parameter, making the purpose unambiguous and distinguishable from sibling tools like get_holdings or get_filings.
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 the agent when to use each identifier value: 'Pass identifier='latest' for the market-wide feed... or a ticker for the stakes indexed on that company.' This is clear usage guidance for the primary parameter. It does not explicitly compare against alternatives (e.g., get_holdings), but the distinction between activist stakes and general holdings is implicit. The guidance is specific enough to correctly invoke the tool for both intended scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CIK, legal name, SIC industry, fiscal-year end, exchanges and website for a ticker, resolved from SEC EDGAR submissions.
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes | US stock ticker, e.g. 'AAPL'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate safe, read-only, idempotent behavior. The description adds transparency about the data source (SEC EDGAR submissions) and the specific fields returned, providing context beyond the annotations. No contradictions found.
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 sentence that efficiently lists the returned fields and the data source. No unnecessary words or repetition.
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 single parameter, high annotation coverage, and no output schema, the description is nearly complete. It specifies the output fields and source. Minor omission: it does not explicitly state that the tool returns a single company, but this is implied by the ticker parameter.
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?
The input schema has 100% coverage with a clear description for 'ticker'. The description does not add additional meaning beyond the schema's definition, so a baseline score 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 returns specific company profile fields (CIK, legal name, SIC industry, etc.) for a given ticker, resolved from SEC EDGAR. It distinguishes from sibling tools like get_filings or get_fundamentals by specifying the exact output type.
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 usage for retrieving a company profile but lacks explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or conditions, though sibling names provide some context. Usage is implied rather than directly instructed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
8-K material events for a ticker as typed items (2.02 earnings, 5.02 executive change, 1.05 cybersecurity incident, 2.01 acquisition, etc.), each with a notable flag for the market-moving ones and a link to the filing. Pass item to filter to one event type (e.g. '4.02' for every restatement a company filed). Pass ticker='restatements' or 'auditor-changes' for the market-wide red-flag feed of recent item 4.02 / 4.01 8-Ks across all filers.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | For the market-wide feeds: lookback window in days (default 45). | |
| item | No | Filter to a specific 8-K item code, or comma-separated codes, e.g. '4.02' (restatement) or '5.02,2.02'. | |
| limit | No | Number of events, 1-100 (default 20; 50 for feeds). | |
| ticker | Yes | US stock ticker (e.g. 'AAPL'), or 'restatements' / 'auditor-changes' for the market-wide item feed. | |
| notable | No | Only market-moving events (default false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already supply readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by explaining that results are typed items, include a notable flag for market-moving events, link to the filing, and that special ticker values change the tool into a market-wide red-flag feed.
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?
Three sentences that front-load the core purpose, then provide filter and special-mode instructions without redundancy. Every sentence adds functional value, and the description is neither bloated nor under-specified.
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?
For a read-only, filtered-list tool with multiple modes, the description covers the essential behaviors: event types, notable filtering, filing links, item filtering, and market-wide feeds. The schema handles parameter defaults and constraints, and the annotations cover safety, so nothing critical is missing for an agent to invoke the tool correctly.
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 the schema already documents all five parameters with meaningful descriptions. The tool description reinforces examples like '4.02' and the special ticker values, but most of that information is duplicated from the schema rather than adding substantial new meaning beyond the structured definitions.
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 opens with a specific verb and resource: 8-K material events for a ticker, presented as typed items with notable flags and filing links. It also clearly distinguishes the market-wide feed modes ('restatements', 'auditor-changes') from the per-ticker use case, so an agent can tell this apart from filing-level sibling tools like get_filings or search_filings.
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 gives concrete usage instructions: pass an item code to filter to a single event type, pass special ticker values for market-wide feeds, and use notable to isolate market-moving events. It does not explicitly name sibling alternatives or state when not to use this tool, but the context is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent SEC filings for a ticker (10-K/10-Q/8-K) with filing/report dates and document links.
| Name | Required | Description | Default |
|---|---|---|---|
| form | No | Optional form filter, e.g. '10-K', '10-Q', '8-K'. | |
| limit | No | Number of filings to return, 1-100 (default 20). | |
| ticker | Yes | US stock ticker, e.g. 'AAPL'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and open world behavior. The description adds that the output includes filing/report dates and document links, but does not detail other behaviors (e.g., pagination, rate limiting). It adds some value beyond 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, front-loaded sentence with no redundant words. Every part contributes to understanding the tool's core function.
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?
For a simple tool with three parameters and no output schema, the description provides adequate context about the response content. However, it lacks details on the recency or ordering of filings (e.g., defaults to last 20).
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%, providing clear parameter definitions. The tool description adds no additional parameter information, so it meets the baseline expectation.
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 retrieves recent SEC filings for a ticker, mentioning common form types and response contents (dates and links). It distinguishes the tool's purpose but does not explicitly differentiate from sibling tools.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., get_fundamentals, get_insider). The description lacks when/when-not and alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parsed Form D notices — the filing a company makes when it raises money in a private placement under a Regulation D exemption. Each carries the issuer, jurisdiction, industry, amount offered and sold, the exemption, related persons, and date of first sale. Pass a CIK (or ticker if public) for one issuer, or 'latest' for the market-wide feed of new private raises.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of notices, 1-100 (default 20 for latest, 10 per issuer). | |
| identifier | Yes | Issuer CIK (Form D issuers are usually private), a ticker if public, or 'latest' for the market-wide feed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds useful context by listing the output fields and explaining the 'latest' feed behavior. However, it doesn't disclose potential pagination limits, error handling, or any special side effects beyond the schema.
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 sentences, front-loaded with purpose, then usage. No filler words. Every sentence adds value: one defines the resource and its content, the other explains the parameter modes. Excellent structure.
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?
The tool is simple with only two parameters, a complete schema, and comprehensive annotations. The description covers what the data contains, how to query it, and the two ways to use it. No output schema exists, but the description lists the key fields, making it complete enough for an agent.
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 both parameters are already documented. The description adds helpful guidance about CIK versus ticker for private issuers and the default limits, but it largely restates what the schema already provides. A 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 parses Form D notices and lists the key data elements (issuer, jurisdiction, industry, amount, exemption, etc.). It distinguishes itself from generic filing tools by focusing specifically on private placement filings under Regulation D.
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 gives explicit instructions on how to use the tool: pass a CIK, ticker, or 'latest' for a market-wide feed. It also explains the context (private placements under Reg D). It doesn't mention exclusions or compare directly with siblings, but usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Normalized income statement, balance sheet, and cash flow for a US-listed ticker, parsed from SEC EDGAR XBRL. Counts as one request on the Edgrapi plan.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of periods to return, 1-20 (default 5). | |
| period | No | Reporting period (default annual). | |
| ticker | Yes | US stock ticker, e.g. 'AAPL'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about the data source (SEC EDGAR XBRL) and billing plan, which are beneficial beyond the annotations. No contradictions.
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 sentences: first defines purpose and source, second adds billing info. No redundant phrases, perfectly front-loaded and efficient.
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 simplicity (3 parameters, no output schema), the description is complete: it specifies the financial statements returned, data source, and billing cost. Could mention normalization briefly, but not necessary.
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%, so the schema already documents all parameters. The description adds no additional semantic meaning for the parameters beyond what's in the schema, which is adequate but not enhanced.
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 retrieves 'income statement, balance sheet, and cash flow' for a US-listed ticker from SEC EDGAR XBRL. This distinguishes it from siblings like get_ratios or get_filings.
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 mentions the billing impact ('counts as one request'), but does not explicitly state when to use this tool versus alternatives like get_ratios or get_filings. Usage is implied by name and purpose but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A fund's latest 13F portfolio parsed from the SEC information table: every position ranked by value, aggregated by CUSIP across sub-managers, options flagged put/call, and diffed against the prior quarter (new / added / reduced / exited). Identify the fund by a known name (berkshire, burry, ackman, bridgewater, citadel), a CIK, or a filer ticker (BRK-B).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max positions, 1-500 (default 50). | |
| changes | No | Diff vs the prior quarter (default true). | |
| identifier | Yes | Fund name (e.g. 'berkshire', 'burry', 'pershing-square'), a CIK, or a ticker whose company files the 13F (e.g. BRK-B). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that: aggregation by CUSIP, put/call flags for options, and a quarter-over-quarter diff (new/added/reduced/exited). This gives the agent a clear picture of the output shape and processing behavior without contradicting the 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 and enriched with relevant details about output composition and identifier options. It avoids filler and each clause contributes meaning. A slight sentence break at the diff explanation could improve readability, but overall it is well-structured.
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?
For a read-only tool with no output schema, the description adequately describes what the tool returns (positions, aggregation, option flags, diff) and how to specify the fund. The identifier explanation is comprehensive and the annotations cover safety and idempotency. Nothing critical is missing for an agent to call this correctly.
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 the schema already documents all three parameters and their meanings. The description partially reiterates the identifier semantics (providing additional example fund names like 'ackman' and 'bridgewater') and clarifies the default for changes (diff vs prior quarter), but it adds limited new information beyond the schema. Baseline 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 states a specific verb ('get'), a precise resource ('13F holdings'), and details what the output contains (ranked positions, CUSIP aggregation, option flags, quarter-over-quarter diff). It also explicitly lists the accepted identifier forms, making it clear this tool is for fund holdings and distinguishable from siblings like get_company or get_events.
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 clearly states what the tool is for (retrieving a fund's latest 13F portfolio) and how to identify the target fund (name, CIK, or filer ticker). It does not name alternative tools for when this should not be used, but the domain is specific enough that an agent can infer from the sibling list. A brief exclusion note would push this to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parsed SEC Form 4 insider trades for a ticker: owner, role, transaction code (P open-market purchase, S sale, A award, M exercise, F tax withholding), shares, price, dollar value, and a 10b5-1 plan flag. Code P is the only own-money buy signal; A/M/F are automatic compensation. Set form=3/5 for holdings statements or form=144 for notices of proposed sale (an intent-to-sell signal that precedes the Form 4). Pass ticker='latest' for the market-wide feed of the biggest open-market buys, or ticker='clusters' for companies where several insiders bought at once.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | For 'clusters': lookback window in days (default 15). | |
| form | No | Ownership form: 4 (trades, default), 3 (initial holdings), 5 (annual), or 144 (notice of proposed sale — an intent-to-sell signal that precedes the Form 4). | |
| limit | No | Number of results, 1-100 (default 20). | |
| ticker | Yes | US stock ticker (e.g. 'AAPL'), 'latest' for market-wide buys, or 'clusters' for cluster buys. | |
| min_insiders | No | For 'clusters': min distinct insiders (default 3). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond that: it explains that code P is the only own-money buy signal, that A/M/F are automatic compensation, that form=144 is an intent-to-sell signal, and that 'latest' returns the biggest open-market buys. This significantly 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 three sentences but packs dense, high-value information. It front-loads the core function in the first sentence, then explains transaction codes and special modes. Every clause earns its place; no filler or repetition.
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?
For a tool with 5 parameters and no output schema, the description covers all major aspects: return fields, parameter behavior, special modes, and the meaning of transaction codes. It also mentions defaults for 'days' and 'min_insiders' implicitly through schema, and the description is self-sufficient for an agent to decide when and how to invoke it.
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?
Even though the schema covers 100% of parameters, the description adds meaning beyond the schema by explaining special values for 'ticker' ('latest' and 'clusters') and the semantic difference between form types. It also clarifies the business meaning of transaction codes, which is not in the schema. This raises the score well above the 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 opens with a specific verb and resource: 'Parsed SEC Form 4 insider trades for a ticker'. It lists exact data fields (owner, role, transaction code, shares, price, dollar value, 10b5-1 flag) and distinguishes itself from siblings like get_filings by focusing on parsed insider transactions and offering unique special modes ('latest', 'clusters').
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 clear context for when to use each alternative: it explains the transaction code meanings (P vs A/M/F), directs users to form=3/5 for holdings statements and form=144 for proposed sales, and explains special ticker values 'latest' and 'clusters'. However, it does not explicitly name sibling tools or state when NOT to use this tool, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Margins, returns (ROE/ROA), leverage and liquidity ratios for a ticker, derived from SEC EDGAR fundamentals. Price-based ratios (P/E, P/B) excluded.
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes | US stock ticker, e.g. 'AAPL'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safe, non-mutating behavior. Description adds context about derivation source and excluded ratio types, beyond 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?
Two sentences with no wasted words. First sentence lists ratio categories and source, second clarifies exclusion. Information is front-loaded.
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?
For a read-only retrieval tool with one parameter and no output schema, the description sufficiently covers included/excluded ratios and source, leaving no ambiguity.
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 one parameter described as 'US stock ticker, e.g. AAPL'. Description adds no additional parameter details 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?
Description clearly states it computes margins, returns (ROE/ROA), leverage, and liquidity ratios from SEC EDGAR fundamentals, and explicitly excludes price-based ratios (P/E, P/B). This distinguishes it from siblings like get_fundamentals.
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?
No explicit when-to-use or when-not-to-use guidance. Implied usage is for obtaining fundamental ratios, but alternatives like get_fundamentals are not compared.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Narrative sections from the latest 10-K/10-Q as clean text — Risk Factors (item 1A), MD&A (item 7), Business (item 1), etc. Built for LLM/RAG equity research. Omit 'item' to list the available sections first.
| Name | Required | Description | Default |
|---|---|---|---|
| form | No | Filing type: '10-K' (default) or '10-Q'. | |
| item | No | Section to fetch, e.g. '1A' (Risk Factors) or '7' (MD&A). Omit to list available sections. | |
| ticker | Yes | US stock ticker, e.g. 'AAPL'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is readOnly, openWorld, idempotent, and not destructive. The description adds clarity on behavioral traits: it retrieves the latest filing, returns 'clean text', and provides a listing mode when 'item' is omitted. This complements the annotations well, though some details like error handling are missing.
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 extremely concise—two sentences that front-load the core purpose and examples, followed by a specific usage hint. Every word earns its place, with no redundancy or irrelevant information.
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 lack of an output schema, the description could be more explicit about the return format (e.g., plain text, multiple sections at once). It implies a list when 'item' is omitted and a single section when provided, but this is not fully spelled out. The description is sufficient for basic usage but leaves some gaps for an AI agent.
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%, so parameters are well-documented. The description reinforces the behavior of omitting 'item' to list sections, which is already in the schema description for 'item'. It adds minimal new semantics beyond reminding the agent of this optional feature, resulting in a baseline score.
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 retrieves narrative sections from the latest 10-K/10-Q filings, listing specific items (Risk Factors, MD&A, Business). The verb 'get' matches the tool name, and the resource is distinctly different from sibling tools (company, events, filings, etc.), making its purpose unambiguous.
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 the useful hint to omit 'item' to list available sections, which helps the agent decide when to call without parameters. However, it lacks explicit guidance on when not to use this tool, prerequisites (e.g., valid ticker), or comparison to alternatives among siblings. The context is adequate but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The company's subsidiaries and their jurisdictions of incorporation, parsed from Exhibit 21 of its latest 10-K. Best-effort parse of an HTML exhibit; empty for filers that list only significant subsidiaries or file no Exhibit 21.
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes | US stock ticker or CIK, e.g. 'AAPL'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, open-world, and non-destructive behavior. The description adds meaningful detail beyond those annotations, including the best-effort nature of the parse, the HTML source, and specific conditions leading to an empty result (companies listing only significant subsidiaries or omitting Exhibit 21).
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 concise, information-dense sentences. The primary output and source are front-loaded, followed by necessary caveats, with no redundant or ambiguous phrasing.
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?
Although the tool has only one parameter and useful annotations, it lacks an output schema, and the description does not specify the exact result shape (e.g., array of objects with 'name' and 'jurisdiction' fields). This could leave an agent uncertain about how to consume the response, so completeness is only moderate.
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?
The only parameter, 'ticker', is fully documented in the schema as 'US stock ticker or CIK, e.g. AAPL'. Since schema coverage is 100%, the description adds no additional parameter-level meaning, warranting the baseline score of 3.
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 what the tool returns: the company's subsidiaries and their jurisdictions of incorporation, parsed from Exhibit 21 of the latest 10-K. Reference to Exhibit 21 and the specific data type makes it distinguishable from sibling tools like get_company or get_sections.
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 clear context: data comes from the latest 10-K's Exhibit 21, with important caveats (best-effort parsing and empty results for certain filers). It does not name alternative tools, so it lacks full when-to-use versus when-not-to-use guidance, but the intended scenario is apparent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full XBRL-to-JSON converter. By default returns a company's normalized income statement, balance sheet and cash flow across every reported period, plus a concept index of every us-gaap/dei tag it reports. Pass concept to pull the raw time series for any specific tag(s) beyond the curated fundamentals; pass accession for every concept reported in one specific filing.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | No | SEC CIK, alternative to ticker. | |
| limit | No | Max periods per statement, 1-100 (default 40). | |
| period | No | Statement period (default annual). | |
| ticker | No | US stock ticker, e.g. 'AAPL'. | |
| concept | No | Comma-separated us-gaap/dei tag(s) to return the raw series for, e.g. 'Revenues,Assets'. Omit for normalized statements + concept index. | |
| accession | No | An accession (e.g. '0000320193-24-000123') to return every XBRL concept reported in that one filing. Overrides ticker/concept. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful behavioral context beyond that: it returns data 'across every reported period,' provides a full concept index, and lets `accession` override the company-level modes — all useful expectations for an agent.
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 sentences with no filler. The first sentence front-loads the core purpose and default behavior; the second covers the two specialized parameters compactly. Every clause earns its place.
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?
For a tool with six optional parameters and no output schema, the description gives a solid mental model of what comes back. It covers the default output, the optional overrides, and the filing-scoped behavior. A slightly fuller note on the JSON return format or company-identifier requirements would make it fully complete, but the current level is strong.
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 the baseline is 3. The description adds value by explaining that `concept` retrieves 'raw time series' beyond the 'curated fundamentals' and that `accession` returns 'every XBRL concept reported in that one filing,' clarifying the intent of those parameters beyond their schema descriptions.
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 names a specific action and resource: 'full XBRL-to-JSON converter' for SEC XBRL data. It then enumerates concrete outputs — normalized income statement, balance sheet, cash flow, and a concept index — making its purpose unmistakable and distinct from financial-data siblings.
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?
It explains three usage modes: the default normalized-statement output, passing `concept` for raw tag time series, and passing `accession` for single-filing concept dumps. This gives clear contextual guidance, though it does not explicitly contrast with siblings like get_fundamentals or get_filings, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map any one of a ticker, CIK, or CUSIP to the canonical SEC entity: legal name, CIK, ticker(s), exchange, SIC industry and sector, state of incorporation, and location. The foundational lookup for identifying a filer.
| Name | Required | Description | Default |
|---|---|---|---|
| cik | No | SEC CIK, e.g. '320193' (zero-padding optional). | |
| cusip | No | 9-character CUSIP, e.g. '037833100'. | |
| ticker | No | US stock ticker, e.g. 'AAPL'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate readOnlyHint, idempotentHint, openWorldHint, and non-destructiveness. The description adds useful behavioral context by listing the resolved fields (legal name, CIK, ticker(s), exchange, SIC, state of incorporation, location) and by clarifying that any one identifier maps to the same canonical entity.
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 focused sentences with no filler. The core action and accepted inputs lead, followed by the output payload and the tool's broader role. Every sentence adds information.
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?
With no output schema, the description appropriately lists the resolved fields and frames the tool as a canonical lookup. It could further clarify whether multiple identifier parameters may be combined or how conflicts are resolved, but the essential call-and-response behavior is sufficiently covered.
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 the baseline is 3, but the description adds semantic value by stating that the three identifier parameters are interchangeable entry points into the same entity resolution. This relationship among parameters is not expressed in the individual schema descriptions.
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 uses the specific verb 'Map' and names the exact resource ('canonical SEC entity') plus the three accepted identifier types. It enumerates the output fields, making the tool's purpose unmistakable and distinct from sibling data-retrieval tools.
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 frames the tool as 'The foundational lookup for identifying a filer,' which gives clear context for when an agent should use it. It does not explicitly name sibling alternatives or when-not-to-use conditions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the full text of every SEC filing since 2001 (the EDGAR full-text index). Returns matching filing documents with company, form, date, 8-K item codes, and a SEC.gov link. Quote a phrase for exact match; filter by form and date range.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query. Quote a phrase ("climate change") for an exact match; space-separated terms are ANDed. | |
| enddt | No | Only filings on/before this date, YYYY-MM-DD. | |
| forms | No | Comma-separated form filter, e.g. '8-K' or '10-K,10-Q'. | |
| limit | No | Results to return, 1-100 (default 20). | |
| offset | No | Pagination offset into the result set (default 0). | |
| startdt | No | Only filings on/after this date, YYYY-MM-DD. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds useful context: it covers filings since 2001, returns a SEC.gov link, includes 8-K item codes, and describes exact-match behavior. It does not go into pagination or rate limits, but the safety profile is already established by 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?
Three sentences with the core purpose and scope front-loaded, followed by return format and query tips. Every sentence contributes information and none repeats the schema verbatim.
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?
Because there is no output schema, the description names the key returned fields (company, form, date, 8-K item codes, SEC.gov link), which is sufficient for an agent to interpret results. The remaining minor gap is that it does not describe pagination behavior, though limit and offset are fully documented in the schema.
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 the input schema already documents every parameter. The description's 'quote a phrase' and 'filter by form and date range' guidance adds no new semantics beyond the schema definitions for q, forms, startdt, and enddt.
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 identifies a specific verb and resource: 'Search the full text of every SEC filing since 2001 (the EDGAR full-text index).' It also names concrete return fields. However, it does not explicitly explain how this differs from the sibling get_filings, leaving the distinction implicit.
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 usage via 'Quote a phrase for exact match; filter by form and date range,' which gives query tips. It never states when to prefer this tool over siblings such as get_filings, nor does it mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_form_dget_subsidiariesget_events4 fields changedInput schema / properties / daysAdded value: +{
+ "description": "For the market-wide feeds: lookback window in days (default 45).",
+ "type": "integer"
+}Input schema / properties / itemAdded value: +{
+ "description": "Filter to a specific 8-K item code, or comma-separated codes, e.g. '4.02' (restatement) or '5.02,2.02'.",
+ "type": "string"
+}Input schema / properties / limit / descriptionPrevious value: -"Number of events, 1-100 (default 20)."New value: +"Number of events, 1-100 (default 20; 50 for feeds)."Input schema / properties / ticker / descriptionPrevious value: -"US stock ticker, e.g. 'AAPL'."New value: +"US stock ticker (e.g. 'AAPL'), or 'restatements' / 'auditor-changes' for the market-wide item feed."get_sharesget_xbrlresolve_entitysearch_filingsget_activistget_holdingsget_insider1 field changedInput schema / properties / formAdded value: +{
+ "description": "Ownership form: 4 (trades, default), 3 (initial holdings), 5 (annual), or 144 (notice of proposed sale — an intent-to-sell signal that precedes the Form 4).",
+ "enum": [
+ "3",
+ "4",
+ "5",
+ "144"
+ ],
+ "type": "string"
+}get_insider4 fields changedInput schema / properties / daysAdded value: +{
+ "description": "For 'clusters': lookback window in days (default 15).",
+ "type": "integer"
+}Input schema / properties / limit / descriptionPrevious value: -"Number of filings, 1-100 (default 20)."New value: +"Number of results, 1-100 (default 20)."Input schema / properties / min_insidersAdded value: +{
+ "description": "For 'clusters': min distinct insiders (default 3).",
+ "type": "integer"
+}Input schema / properties / ticker / descriptionPrevious value: -"US stock ticker, e.g. 'AAPL'."New value: +"US stock ticker (e.g. 'AAPL'), 'latest' for market-wide buys, or 'clusters' for cluster buys."get_eventsget_insiderget_companyget_filingsget_fundamentalsget_ratiosget_sectionsNormalized SEC EDGAR data for AI agents: XBRL financials, 10-K risk diffs, Form 4 insider trades.
Hosted SEC EDGAR filings: Form 4 insider trades, 8-K events, S-1/IPO registrations. Read-only.
SEC insider filings as clean economic events - Form 4 trades, Form 144 notices, 13D/G stakes.
SEC EDGAR financials, insider trading, and economic data for AI agents. US GAAP + IFRS.
