secedgar-mcp-server

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering the safety profile. The description adds behavioral context beyond annotations by detailing that it resolves multiple identifier types and returns accession numbers for downstream use, which is valuable for understanding the tool's role 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 every clause earns its place. The second sentence adds essential workflow context without redundancy. No fluff 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 presence of a rich output schema and comprehensive annotations, the description is sufficiently complete. It conveys the tool's role as an entry point, the identifier resolution capability, and the link to secedgar_get_filing. It could be slightly more explicit about when to use this vs. secedgar_search_filings, but overall it provides enough context for effective selection.

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 itself adds minimal parameter-level detail, but the schema already thoroughly explains each parameter (e.g., query accepts ticker/name/CIK, filed_after routes to archive pages). The description's mention of 'optional recent filings' ties to the include_filings parameter but adds no new semantics 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 uses specific verbs ('Find', 'retrieve') and resource ('companies', 'entity info'), and clearly distinguishes itself as the entry point for EDGAR workflows, resolving tickers/names/CIKs to entity details. This differentiates it from sibling tools like secedgar_search_filings or secedgar_get_filing, while hinting at its role as a precursor to the latter.

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 states it is the 'Entry point for most EDGAR workflows' and explains how accession numbers feed into secedgar_get_filing, giving clear context for when to use it. It does not explicitly list exclusions or alternatives (e.g., when to prefer secedgar_search_filings), but the implied workflow guidance is strong.

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

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

It discloses non-obvious behaviors: the same dedup and tag priority as secedgar_get_financials, point-in-time alignment for balance-sheet/entity-info concepts, matrix trimming limits, and how failed companies and gaps are reported (never interpolated or zero-filled). This goes well beyond the readOnlyHint, openWorldHint, and idempotentHint 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 long but front-loaded with the core purpose and contains dense, valuable behavioral information. Every sentence earns its place, though it could be tightened slightly without losing 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?

Even with a rich input schema, annotations, and an output schema, the description adds essential context: the inline vs. materialized dataframe distinction, failure/gap reporting, caveats about off-calendar filers and unit mismatches, and a pointer to secedgar_dataframe_query for full-series access. This makes the tool's behavior fully predictable.

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?

Input schema descriptions already cover all parameters with rich details (e.g., periods being an upper bound, concepts accepting friendly names or raw tags, taxonomy usage caveats). The description adds global context but does not materially enhance parameter-level semantics beyond what the schema 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 first sentence states a specific action and scope: 'Compare 2-10 named companies across 1-8 XBRL concepts, aligned on calendar periods.' It also explicitly differentiates from sibling tools by labeling itself as the 'middle shape' between secedgar_get_financials and secedgar_fetch_frames.

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 directly tells when to use it: 'reach for it when the question names the companies.' It contrasts with the one-company/one-concept full history of secedgar_get_financials and the one-concept/one-period all-company behavior of secedgar_fetch_frames, and points to secedgar_dataframe_query for further analysis.

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

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

Annotations already declare readOnlyHint, openWorldHint false, and idempotentHint true. The description adds useful context beyond these, such as the list of source tools, creation/expiry timestamps, row count, column schema, and truncation status. This gives the agent a good sense of what data will be returned without contradicting 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 and well-structured: two sentences, front-loaded with the main verb and resource, then a clear enumeration of what each entry surfaces. 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?

With an output schema present and one optional parameter documented in the schema, the description provides sufficient context. It explains the exact purpose, the source tools, and the metadata fields included, making it complete for a listing/metadata 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?

The schema already provides full coverage for the single optional parameter 'name' (100% coverage), explaining it can target a single dataframe or be omitted to list all. The description adds no additional parameter semantics beyond what the schema already states, so the 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 clearly states the tool's function with a specific verb "List" and specific resource "dataframes" materialized by a named set of source tools. It distinguishes from sibling tools like dataframe_query by focusing on metadata (row count, column schema) rather than data querying.

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 by listing which tools generate dataframes and what each entry contains, but it does not explicitly state when to use this tool versus alternatives. No when-to-use or when-not-to-use guidance is provided, though the context implies it is for inspecting dataframe metadata.

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

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

Annotations already declare readOnlyHint=true, but the description adds concrete rejected operations (writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file table functions) and denied system catalogs. It also discloses that register_as creates a fresh TTL, which is beyond the structured fields. This is genuinely helpful behavioral context.

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: purpose, restrictions, and chaining behavior. Every sentence delivers distinct information with no redundant fluff, and the key verb and resource appear in the first sentence.

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 4 parameters fully documented in the schema, an output schema, and annotations, the description adds the necessary restrictions, data source context, and chaining behavior. The tool is complex enough that a shorter description would leave gaps, but this covers the relevant gotchas (read-only, system catalogs, TTL).

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 descriptions cover 100% of parameters with detailed semantics (BIGINT serialization, row limits, df_<id> naming, preview default). Since the description text itself does not add parameter meaning beyond referencing register_as's TTL (already in schema), the 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 clearly states the tool runs single-statement SELECT queries against canvas dataframes, names the source tools (secedgar_fetch_frames, secedgar_search_filings, secedgar_get_financials), and distinguishes itself from siblings like secedgar_dataframe_describe by focusing on querying rather than listing or fetching.

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 after dataframes are registered by fetch/search/financials tools, and explicitly directs users to secedgar_dataframe_describe for listing available dataframes. It does not explicitly state when not to use it (e.g., vs. fetching new data), but the read-only constraint and the targeting of registered dataframes make the context clear. A more explicit alternative statement would push this to a 5.

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

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

The description goes far beyond the readOnlyHint/openWorldHint/idempotentHint annotations by disclosing important behavioral nuances: pagination semantics (offset/next_offset, stable and gap-free), the materialization of `df_<id>` when a canvas is available, the presence of `unqueried_tags` for same-meaning tags, and the risk of silently omitting filers when `related_tags` differ. It also warns about XBRL scale-factor anomalies and fiscal-year mixing via `value_distribution` and `period_end_range` — exactly the kind of context an agent needs.

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 solid paragraph of dense, purposeful prose. Every clause adds a distinct piece of guidance (pagination, tag discovery, related tags, data-quality flags), yet it is not broken into bullet points or sections, which could improve scannability. For the complexity of the tool, it is concise enough, though slightly longer than necessary for a quick read.

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, the description provides a remarkably complete picture: what the inline response looks like, how to page, how the full response materializes, how to handle tag ambiguity, how to avoid silent omission, and how to interpret data-quality signals. The presence of an output schema does not diminish the need for this context, and the description covers all major use cases and caveats. There is no hint of missing information that would leave an agent confused.

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 already covers all six parameters with clear descriptions and 100% coverage, so the baseline is 3. The description adds extra semantic value by explaining that friendly names map to the same set as secedgar_get_financials, that unit is ignored for friendly names with known units, and that period 'I' instant vs duration semantics matter for balance-sheet vs income items. This goes beyond the schema but does not radically change parameter understanding, so a 4 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 starts with a specific verb+resource: "Fetch SEC XBRL frames for one concept × one period across all reporting companies," which clearly distinguishes it from sibling tools like secedgar_get_financials (single company) and secedgar_company_search. It also explains the core output (a ranked page of companies) and the key difference between inline and full frames responses.

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 rich context on when to use this tool: for cross-company XBRL concept lookup, and how to handle friendly names vs raw tags, multiple tags, and related tags. It explicitly mentions related tools (secedgar_search_concepts, secedgar_dataframe_query) and gives actionable guidance on UNION/COALESCE and querying `related_tags` separately. However, it does not explicitly state when NOT to use this tool versus alternatives, so it stops short of a full when/when-not specification.

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

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

Even with readOnlyHint and idempotentHint annotations, the description reveals crucial behavior: 'The returned list is unranked: the search index scores by text relevance, which carries no signal about position size,' and that a quarter inside its deadline 'returns nothing.' These insights go beyond the annotations and meaningfully shape caller expectations.

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 longer than average but every sentence carries useful information, covering purpose, alternatives, matching trade-offs, and limitations. It could be slightly tighter—the cusip-vs-name explanation could be shortened without losing meaning, but the structure is logical and front-loaded with the core action.

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 that could easily be confused with secedgar_get_institutional_holdings, the description covers the key differentiator, provides guidance on tricky inputs (cusip, quarter), and discloses output limitations (unranked list). With a rich schema and output schema present, the description leaves no critical gaps for a caller to trip on.

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 description adds essential parameter-level nuance not in the schema: it explains that cusip is the precise match key and that 'A CUSIP cannot be derived from a ticker here,' requiring a lookup from secedgar_get_institutional_holdings. It also clarifies the role of the issuer parameter when cusip is supplied, and the quarter omission behavior, complementing the already thorough 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 opening sentence specifies the exact action and scope: 'Find which institutional managers reported holding an issuer, by searching 13F-HR information tables for one reporting quarter.' It clearly differentiates from the sibling secedgar_get_institutional_holdings by describing this as the 'reverse direction', leaving no ambiguity about which tool to pick.

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 directs when to use this tool versus secedgar_get_institutional_holdings, provides a strong recommendation to 'prefer cusip whenever one is known,' and explains why name matching is unreliable. It also states the $100M filing exemption, setting expectations for when no managers may appear, and clarifies quarter-deadline behavior.

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

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description adds critical behaviors: how reporting persons are listed separately and why summing double-counts, the coverage start date and legacy filing limitations, and the materialization of a df_<id> dataframe when a canvas is available. 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 dense, about 200 words, but every sentence contributes unique information. It is front-loaded with the core purpose, then progresses to distinctions, pitfalls, coverage limits, and output materialization. Slightly long but appropriately structured for the tool's 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?

With an output schema present, the description need not detail return values. It covers data source, directionality, form semantics, double-counting pitfall, coverage date, legacy handling, and dataframe integration. This is comprehensive for a tool with 4 parameters and one enum, leaving no significant gaps.

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%, providing baseline 3. The description adds meaningful context beyond the schema: the issuer vs manager directionality, the substantive difference between 13D and 13G forms, and the cost/depth implication of the limit parameter. These enrich the parameter meanings without duplicating 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 opens with a specific verb and resource: 'List the 5%-and-over beneficial owners of a public company, parsed from the structured SCHEDULE 13D and SCHEDULE 13G filings made about it.' It further distinguishes from the sibling secedgar_get_institutional_holdings by noting the opposite input direction (issuer vs manager), making the 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 explicitly contrasts with secedgar_get_institutional_holdings ('which is the opposite direction'), and clarifies that passing an investment manager returns almost always empty. It also explains when to prefer 13D over 13G based on the activist/passive distinction, giving clear usage context and exclusions.

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

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

Discloses important behaviors beyond annotations: truncated responses require next_offset, section takes precedence over offset, XBRL artifacts are excluded by default, and binary documents are rejected. Annotations already indicate read-only/idempotent, but description adds substantive pagination and content-handling context.

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 concise, front-loaded sentences. The core purpose is stated first, followed by actionable pagination/section guidance. No filler or 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?

Description plus richly detailed schema and output schema cover large document pagination, section navigation, content limits, XBRL filtering, and document selection. Enough context for an agent to invoke correctly in varied scenarios.

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?

Input schema has 100% parameter description coverage with detailed explanations, so the baseline is 3. The main description references offset/section usage, but largely reiterates what the schema already says; it adds minimal new parameter-level meaning.

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 uses the specific verb 'Fetch' and identifies the resource as 'a specific filing's metadata and document content by accession number.' It clearly distinguishes this retrieval tool from search-oriented siblings by targeting a single 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?

Provides explicit guidance for large filings: use offset/next_offset for multi-page access and section for heading jumps. It does not explicitly name alternative tools, but the context makes it clear that this tool is for retrieving a specific filing rather than searching.

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

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

Annotations already declare readOnly/idempotent. Description adds non-obvious behavioral details: 'Handles historical tag changes and deduplicates data automatically' and accepts friendly or raw tag input. 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?

Three sentences with front-loaded purpose, clear examples, and no redundancy. The cross-reference to search_concepts is useful and brief.

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 an output schema and rich annotations, the description covers the purpose, key input semantics, automatic dedup/historical handling, and the discovery workflow. This is sufficient for an agent to select and 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 covers all 5 params with detailed descriptions (100% coverage). Description adds meaning to `concept` by explaining friendly names auto-resolve to XBRL tags and manage historical changes, which goes beyond the schema's examples.

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 opens with 'Get historical XBRL financial data for a company' — a specific verb, resource, and scope. It distinguishes from sibling secedgar_search_concepts by referencing it for discovery, and from snapshot tools by emphasizing 'historical'.

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 workflow guidance: 'Discover available friendly names with secedgar_search_concepts'. Clearly indicates this tool retrieves financial data and search_concepts is for discovering names. However, it does not explicitly exclude alternatives like secedgar_fetch_frames or describe when to use them.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses that data is parsed from NPORT-P filings, that holdings are as of report_period_date not today, that pagination is stable via offset/next_offset, and that the full report is registered as df_<id>. These are behavioral traits not captured in 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?

While long, the description is densely informative with no wasted words. It front-loads the core purpose in the first sentence, then logically expands to context, fields, ordering, pagination, disambiguation, and temporal caveat. Every sentence adds a distinct piece of operational knowledge.

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?

This is a complex 5-parameter tool with an output schema, but the description covers the returned fields, ordering, pagination mechanics, the series/report matching rule, the date semantics, and the dataframe integration. There's no obvious gap for an agent to misuse the 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?

Even though schema coverage is 100%, the description enriches parameter meaning: it explains fund input resolution (ticker vs series vs CIK), the relationship between series_id and fund, the limit and offset behavior ('largest-first by percent of net assets', 'paging is stable and gap-free'), and the report_date's relationship to fiscal quarters. The narrative connects all params to the NPORT-P domain.

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 'List what an ETF or mutual fund holds, parsed from the NPORT-P portfolio report it files with the SEC every quarter' — a specific verb+resource. It explicitly differentiates from siblings: 'secedgar_get_institutional_holdings and secedgar_find_holders answer who owns a company, this answers what a fund owns.' This is exactly the kind of distinction needed.

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 names the alternative tools for ownership queries and frames the directionality ('opposite direction'), giving clear guidance on when to use this tool vs them. It also covers the use-case for trusts with multiple series: 'a trust with several funds needs the specific fund named — pass its ticker or series_id,' and warns about the reporting delay so users understand the temporal context.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are complemented by description details: the inline list is a 'preview capped at limit' with the full set materialized as 'df_<id>' when canvas is available. It also discloses coverage of nonDerivative and derivative transactions, adding behavioral context beyond 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 front-loaded with the core purpose and then elaborates on return fields and usage. While longer than the minimal example, each sentence contributes value, including the SQL snippet; a slight trim could improve conciseness.

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 description is highly complete for a tool of this complexity: it lists return fields, distinguishes transaction types, explains the canvas/df_<id> behavior, and cross-references related tools. The presence of an output schema does not make the description redundant; it adds practical usage context.

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?

Although all parameters have schema descriptions, the tool description adds meaning: 'transaction_type' maps 'purchase' to code P and 'sale' to code S, and 'limit' is clarified as the cap on the preview list. 'ticker_or_cik' is explicitly stated to refer to the issuer, not the reporting person.

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 'Fetch Form 4 insider transactions...' which is a specific verb+resource+scope. It clearly differentiates from sibling tools by noting that secedgar_search_filings should be used for broader date-range queries or across companies.

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 directs users to alternatives: 'Use secedgar_search_filings with forms=["4"] for broader date-range queries or to search across all companies.' It also instructs to use secedgar_dataframe_query for aggregation, providing clear when-to-use guidance.

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

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

Discloses substantial behavioral details beyond the readOnlyHint/idempotentHint annotations: parsing of XML, ambiguity handling (returns candidates for shared names), default consolidation behavior, stable pagination, materialization as a dataframe df_<id>, and exemptions for small filers. 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 long but structured: main purpose, reverse direction, result fields, consolidation, paging, dataframe, exemption, and related tools. Each sentence contributes unique information, though some editing could tighten phrasing without losing 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?

Covers return fields, pagination mechanics, consolidation options, dataframe materialization, edge cases (ambiguous names, exempt institutions), and related tools. Given the tool's complexity and an output schema, this description provides comprehensive contextual guidance.

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 adds meaningful context: ticker_or_cik is clarified as the institutional filer (not a portfolio company) with an example CIK and ambiguity resolution; limit, offset, quarter, and consolidate each gain practical usage details like paging stability and quarter-to-filing-window mapping.

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 'Fetch 13F-HR quarterly institutional holdings by parsing the SEC EDGAR information table XML', giving a specific verb, resource, and mechanism. It clearly distinguishes the directionality from its sibling by stating 'For the reverse direction — which institutions hold a given portfolio company — use secedgar_find_holders'.

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?

Explicit guidance is provided for when to use this tool versus alternatives: 'use secedgar_find_holders' for reverse lookups, 'Use secedgar_search_filings with forms=["13F-HR"] for broader search', and 'query it with secedgar_dataframe_query' for aggregation. It also notes that institutions with <$100M in 13(f) securities may not file, setting expectations.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds substantial non-obvious traits: it pages into the SEC archive for filings older than the recent window, materializes the full filtered set as a dataframe when limit is exceeded, and decodes both x.xx and legacy integer item codes. These details inform the agent about data volume and access behavior beyond what annotations alone convey.

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 dense and front-loaded with the primary purpose, but it runs several sentences long, covering item-code scope, numbering regimes, archive paging, and dataframe materialization. Each sentence earns its place, and the structure is logical, though a few clauses could be trimmed without losing meaning. It remains appropriately sized for the tool's 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's complexity (5 parameters, mixed item-code vocabularies, archive paging) and the existence of a rich output schema, the description covers all necessary context: how it differs from siblings, what to expect for press releases, how date filters extend reach, and the dataframe materialization behavior. It is complete 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?

The input schema already provides 100% parameter descriptions, including the full item-code enum and detailed semantics for filed_after/before. The main description adds value by providing concrete examples of item codes (1.01, 2.02, 4.02, 5.02) and explaining the impact of filtering on legacy codes, reinforcing the schema without redundancy. It slightly exceeds the baseline because it contextualizes how parameters interact with the archive paging behavior.

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 precise verb+resource statement: 'Retrieve a company's 8-K filings with their item codes decoded, optionally filtered to specific items.' It clearly distinguishes itself from sibling tools by noting that secedgar_search_filings and secedgar_company_search cannot see item codes, making this the only way to filter by material-event item level.

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 names alternative tools and explains why this one is narrower: 'filtering by them is narrower than any form-level filter in secedgar_search_filings or secedgar_company_search, neither of which can see items.' It also provides concrete guidance on pairing old and new numbering regimes when the date window spans the changeover, and clarifies that press releases are typically EX-99 exhibits, directing users to secedgar_get_filing.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses significant behavioral details: duration concepts report latest full year and latest single quarter while balance-sheet/entity-info concepts report point-in-time; gaps are listed with tried tags and never zero-filled or interpolated; dedup/tag priority matches secedgar_get_financials. 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 front-loaded with the core purpose, followed by comparative guidance and behavioral details. Although multi-sentence, every sentence earns its place—no tautology or filler. It is appropriately sized for a tool with nuanced period/gap behavior.

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 an output schema present, return values don't need explanation. The description covers grouping by statement, period semantics, gap handling, consistency with sibling tools, and usage boundaries. It is fully self-sufficient for an agent to select and 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 coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema, e.g., taxonomy behavior ('ifrs-full covers only the concepts with confirmed IFRS tag variants and the rest... come back under gaps') and period_type nuance ('Balance-sheet and entity-info concepts are point-in-time and always report their latest instant value regardless of this setting'). Company param is simple, but the added context for other params justifies a 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 opens with a specific verb and resource: 'Build a company financial profile in one call: the latest value of every supported XBRL concept, grouped by statement.' It immediately distinguishes from siblings by noting it replaces a run of secedgar_get_financials calls and later directs to secedgar_get_financials for time series and secedgar_compare_companies for side-by-side comparison.

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?

Explicit usage guidance is provided: use when the question is 'what do this company's financials look like right now'. It also names clear alternatives: secedgar_get_financials for full time series and secedgar_compare_companies for comparison, fulfilling both when-to-use and when-not-to-use criteria.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: empty search returns the full catalog, substring matching is case-insensitive across friendly names, labels, and XBRL tags, and reverse-lookup is supported. This goes beyond the annotations and schema to clarify actual 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 two concise sentences in the main body, front-loaded with purpose and usage, followed by illustrative examples. Every sentence earns its place; there is no wasted text or redundancy with schema 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's moderate complexity, the description covers purpose, usage, edge behavior (empty search), and examples. An output schema exists, so return format need not be explained. Annotations cover safety and idempotency. The description is complete for an agent to select and invoke the tool effectively.

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 rich parameter descriptions (e.g., group enum meanings, search examples). The description further enhances parameter understanding by explaining reverse-lookup semantics and how the search param matches against multiple fields. This adds meaning beyond the schema's 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 clearly states the tool's function: 'Search supported XBRL financial concepts by keyword, statement group, or taxonomy.' It uses a specific verb and resource, and explicitly distinguishes itself from sibling tools by directing use before secedgar_get_financials or secedgar_fetch_frames to discover friendly names.

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 guidance: 'Use before secedgar_get_financials or secedgar_fetch_frames to discover the right friendly name, or pass a raw XBRL tag... to reverse-lookup.' It also explains the empty search behavior, giving clear context for when and how to use the tool versus alternatives.

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

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

The description discloses extensive behavioral traits beyond the readOnly/openWorld/idempotent hints: pre-2001 archive handling, the 2001 boundary split and merge, SEC rate caps with a 50-document scan limit, sort-mode behavior on browse paths, pagination deep-dive caveats, form name changes (SC 13D vs SCHEDULE 13D), and insider filings indexed by person. These details give the agent a realistic model of the tool's constraints and quirks.

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?

Although the description is lengthy, it is front-loaded with a clear one-line purpose and every subsequent sentence conveys a distinct operational detail or limitation. The flow moves from high-level capability to specific edge cases (boundary splitting, rate limits, pagination), and there is no filler or redundancy relative to the tool's 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's complexity and the existence of an output schema, the description covers all critical behavioral contexts: start/end date handling, index coverage, entity targeting, sort semantics, pagination limits, form-type nuances, and alternative tools. The output schema handles return values, so no gap remains for an agent to select and 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?

The input schema already covers all parameters in detail (100% coverage), so the baseline is 3. The description adds cross-parameter semantics that the schema does not: how date ranges interact with index boundaries, the need for entity targeting when pre-2001 full-text is used, and the source tagging of merged results. This enriches parameter understanding, raising the score to 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 opens with 'Search EDGAR filings since 1993,' immediately stating a specific verb and resource. It distinguishes itself from siblings like secedgar_get_filing or secedgar_company_search by focusing on full-text and archive search capabilities, and further clarifies the scope with index coverage and entity targeting.

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 alternatives, e.g., 'Use secedgar_get_insider_transactions to retrieve parsed ownership XML' when ownership transaction details are needed. It also gives clear when-not guidance, such as 'A date range alone is not a valid search; pair it with forms or entity targeting' and explains when pre-2001 free-text requires entity scope, helping the agent decide between modes.

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