secedgar-mcp-server

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

Annotations already cover readOnlyHint, openWorldHint, and idempotentHint, so the description's burden is reduced. The description adds the linkage that accession numbers in results feed secedgar_get_filing, which is useful context beyond annotations. However, it does not disclose any other behavioral traits (e.g., potential pagination, response size, or that searches may return multiple entities), leaving those to be inferred from the schema and 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 two sentences with no filler. The first sentence front-loads the core purpose ('Find companies and retrieve entity info with optional recent filings'), and the second sentence adds the workflow context and linkage. Every clause earns its place, and the structure is clear 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?

The description is complete for a tool that has a rich output schema and thorough parameter schemas. It explains the workflow linkage to secedgar_get_filing, which is the most important cross-tool context. It does not need to explain return values since the output schema exists. The only minor gap is the lack of explicit guidance on when to set include_filings to false, but that is covered in the parameter schema. Overall, nothing critical for a correct invocation is missing.

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 every parameter is thoroughly documented in the input schema. The description does not add extra meaning beyond what the schema provides—it mentions that the tool 'resolves tickers, names, or CIKs' which maps to the query parameter, but that is already in the query parameter's description. With full schema coverage, a score of 3 is the appropriate baseline; the description provides marginal added value but does not compensate for any gaps.

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 a specific resource ('companies', 'entity info'). It clearly states what the tool does: resolves tickers, names, or CIKs to entity details. It also differentiates from siblings by naming secedgar_get_filing as the downstream tool that consumes the accession numbers, which distinguishes it from secedgar_search_filings and secedgar_get_filing.

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

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

The description frames this as the 'entry point for most EDGAR workflows' and explains how its results feed into secedgar_get_filing, providing clear direction on when to use it. However, it does not explicitly state when NOT to use it (e.g., for direct filing lookup without entity resolution) or mention alternatives like secedgar_search_filings. It implies the flow rather than spelling out exclusions, which is strong but not fully explicit.

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 provide readOnlyHint=true, openWorldHint=true, and idempotentHint=true, which already establish the safety profile. The description adds substantial behavioral context beyond these: it discloses that balance-sheet concepts align on point-in-time snapshot periods, that companies failing to resolve are excluded from results without halting, that gaps are never interpolated or zero-filled, and that off-calendar filers and unit mismatches are surfaced in caveats. This is rich behavioral disclosure. It falls just short of 5 because it doesn't explicitly state that it performs read-only operations or describe the return structure (though the output schema covers that).

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 dense paragraph, but it is front-loaded with the core purpose and positioning, then flows into behavioral nuances. Every sentence carries meaningful information: scope, placement among siblings, read semantics, period alignment, matrix behavior, failure handling, gap handling, and caveats. It is not overly verbose for its content density, though it could hypothetically be split into two paragraphs for readability. The front-loading of the purpose and sibling distinction is exemplary.

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 multi-company, multi-concept comparison tool with 5 parameters, an output schema, and detailed annotations, the description covers all necessary operational aspects: scope limits, alignment behavior, failure handling, gap reporting, interpolation policy, period trimming, and the dataframe mechanism for further analysis. The only potentially missing element is an explicit statement of what the return payload looks like, but the output schema exists to convey that. Given the complexity and the richness of the surrounding structured metadata, the description is complete.

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 thoroughly. The description adds extra value beyond the schema by explaining the semantics of periods — that it is 'not a guarantee' and that the inline window drops older periods when the product is too large — and by stating that all parameters map to the matrix dimensions. The description also clarifies that a failed company is reported in failed_companies rather than aborting. Since the schema is comprehensive and the description enriches meaning, 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 opens with a precise verb-resource statement: 'Compare 2-10 named companies across 1-8 XBRL concepts, aligned on calendar periods.' It then explicitly positions itself as the middle shape between secedgar_get_financials and secedgar_fetch_frames, making the distinction from siblings unmistakable. This is a clear, specific purpose with no ambiguity.

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 names the sibling tools it sits between and states 'reach for it when the question names the companies.' It also instructs to use ifrs-full 'only when every company in the list reports under IFRS' and warns against mixing IFRS and US GAAP filers. The periods parameter description adds further guidance on when dropped periods stay queryable via secedgar_dataframe_query. This is thorough when-to-use and when-not-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?

Annotations already declare readOnlyHint, openWorldHint=false, and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations, including creation/expiry timestamps and whether data is truncated relative to the upstream source, which helps agents interpret results correctly.

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 dense sentence that front-loads the core action ('List dataframes') and follows with specific, useful detail about sources and returned metadata. Every clause earns its place and there is 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?

The tool is simple: one optional parameter, no required inputs, and an output schema already exists. The description identifies the relevant source tools and the metadata fields provided, which is sufficient for an agent to know 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?

Schema coverage is 100%, so the single optional 'name' parameter is already fully documented in the schema. The description adds no extra parameter details, but with complete schema coverage the 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 opens with a specific verb and resource, 'List dataframes', and clearly scopes which tools' dataframes are included. It also enumerates the fields each entry surfaces, making the tool's purpose unmistakable and differentiating it from query and fetch 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?

The description gives clear context: this tool is for inspecting materialized dataframes and their metadata, not for transforming or querying them. It does not explicitly name alternatives or state when not to use it, but the contrast with sibling tools like secedgar_dataframe_query and secedgar_fetch_frames is implied strongly enough.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description discloses critical behaviors beyond annotations: paging is stable and gap-free due to whole-list slicing, friendly names may map to multiple tags via related_tags, and value_distribution/period_end_range flag anomalies. This transparency helps agents understand edge cases without needing to probe the tool.

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 primary purpose, but it runs as a single long sentence with many embedded clauses. While it contains valuable detail, the structure could be broken into bullet points for easier scanning, yet it remains efficient given the complexity.

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

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

Given the tool's complexity, the description covers paging, concept resolution, unit behavior, and post-processing signals, making it self-sufficient. The output schema is present, so not explaining return values is acceptable, and the description sufficiently orients the 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?

The schema already provides thorough parameter descriptions, but the tool description adds extra meaning such as duration vs. instant period usage, unit handling with friendly concepts, and the offset paging semantics. These additions go beyond the schema coverage and clarify subtle aspects.

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 fetches SEC XBRL frames for one concept and one period across companies, with a specific verb and target. It distinguishes itself by emphasizing the ranked, cross-company nature and paging mechanism, which separates it from other financial data 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 provides clear context for when to use this tool, such as when needing a ranked list of companies for a given concept and period, and mentions friendly names and raw tags. It also hints at alternatives like using secedgar_dataframe_query for full responses, but does not explicitly state exclusions versus all sibling tools.

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, openWorldHint=true, and idempotentHint=true, which inform the agent that this is a safe, read-only, repeatable operation. The description adds valuable behavioral context beyond annotations: the search is based on text relevance, results are unranked, and it performs phrase-matching when CUSIP is absent. These details clarify what the agent can expect, though it doesn't describe pagination or the exact response structure—a minor gap. No contradiction with annotations; the readOnlyHint aligns with the description's search-oriented framing.

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 detailed but not bloated. It front-loads the core purpose and reverse-direction relationship, then systematically covers search precision, limitations, and filing exemptions. While it's longer than typical, every sentence contributes functional guidance—no filler. The structure flows logically from core purpose to key usage nuances.

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 has four parameters, an output schema, and rich annotations. The description covers the search mechanism, precision trade-offs, limitation about ranking, and the filing exemption. The output schema likely documents the return structure, so the description needn't repeat that. Given the tool's complexity (search across 13F tables), the description adequately prepares an agent to invoke it correctly. A minor gap is explicit guidance on how to handle multi-class issuers in practice—though the description does mention 'needs one call per class'.

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 all four parameters are documented in the schema. The description adds meaningful semantic context beyond the schema: it explains why CUSIP is the precise match key, warns about multi-class issuers needing per-class calls, clarifies the limit parameter's behavior (inline rows vs. dataframe materialization), and explains quarter semantics. This adds real value for an agent, complementing the schema details.

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 precisely states what the tool does: finds institutional managers reporting an issuer by searching 13F-HR information tables for one quarter. It explicitly contrasts with its sibling secedgar_get_institutional_holdings (reverse direction), establishing clear differentiation. The phrasing 'takes an issuer and returns its managers' is specific and 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 gives explicit guidance on when to use this tool versus alternatives. It directly references secedgar_get_institutional_holdings as the reverse-direction counterpart, explains that CUSIP is the preferred search path versus issuer name phrase-matching, and warns against over-matching and under-matching. It also clarifies the unranked nature of results and notes the $100M filing exemption, helping an agent decide when this tool is appropriate.

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 annotations indicate readOnlyHint, openWorldHint, and idempotentHint, which the description does not contradict. The description adds useful behavioral context: it explains that each filing is a separate document fetch (cost implication), that amendments are included by default, and that summing percentages across reporting persons would double-count overlapping shares. It does not explicitly state the return format, but the output schema is provided separately. Overall, it enhances transparency 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 detailed and informative, but the sentences are quite long and dense, especially the parameter descriptions. While each sentence adds value, the length could be slightly reduced for readability. However, it is well-organized and front-loads the purpose before diving into nuances.

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

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

Given the complexity of the domain (SEC filings, different schedule types, amendments, coverage start date, potential double-counting), the description is remarkably complete. It covers the tool's purpose, usage, parameters, and caveats. The output schema is provided separately, so return format details are not needed in the description. The description fully equips an agent to decide and use 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?

All four parameters are described with clear semantics. 'issuer' is explained with examples and a warning against passing an investment manager. 'form_kind' explains the difference between 13D and 13G. 'include_amendments' explains why amendments are included by default. 'limit' explains it's both a cost and depth control. The descriptions go beyond the schema to provide meaningful usage guidance.

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 lists 5%-and-over beneficial owners from SEC Schedule 13D/13G filings. It specifies the input is the issuer (company), not the investor, and contrasts it with the sibling tool secedgar_get_institutional_holdings to avoid confusion. The verb 'List' and resource 'beneficial owners' are explicit.

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 explains when to use this tool: to get blockholders of a company, and contrasts it with the institutional holdings tool which takes a manager as input. It also explains the difference between 13D (activist) and 13G (passive) forms, and mentions the coverage start date (2024-12-18) and that earlier stakes are not parseable. This provides clear usage 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?

With readOnlyHint already covering safety, the description adds rich behavioral context: truncated responses with next_offset continuation, character-based pagination with sensible defaults (50K chars ≈ 12,000 words), section-jump precedence over offset, and the fact that binary document entries are rejected. The document parameter surfaces that available documents appear in response metadata, and include_xbrl enumerates exactly which file types are returned. All consistent with readOnly/openWorld/idempotent annotations—no contradiction.

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

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

Three tight, front-loaded sentences. The first states the core purpose; the second explains large-filing pagination with a concrete scale example; the third covers section jumping. Every sentence covers distinct functionality 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?

For a tool fetching potentially enormous filings, the description anticipates every practical edge case: long-document truncation (offset/next_offset), retrieval size limits (content_limit with rationale), navigation costs (section jump), and the XBRL noise problem on large filings. An output schema exists, so return-format documentation is not required here. The only minor gap—section matching semantics—is acknowledged and deflected cleanly via the outline-returning error behavior.

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 parameter descriptions add substantial non-obvious value: offset explains the char-based continuation contract with next_offset, section documents its precedence and error-recovery behavior ('On a miss, the error message includes the detected outline'), content_limit gives practical calibration anchors (12K words, when to raise to 200K), and include_xbrl enumerates concrete file patterns. These go well beyond restating parameter names.

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+resource: 'Fetch a specific filing's metadata and document content by accession number.' It clearly establishes the accession-number addressing model that differentiates it from siblings like secedgar_company_search or secedgar_get_financials. The purpose is unambiguous even without opening the schema.

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 clear usage context: when to page with offset/next_offset ('10-K, S-1 can exceed 1M chars') and when to use section jumping instead. Cross-references in parameter descriptions route users to secedgar_company_search and secedgar_search_filings for obtaining the accession number. However, it stops short of explicitly stating when NOT to use this tool versus a named sibling—exclusions are implied rather than stated.

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 declare read-only, open-world, idempotent. Description adds 'Handles historical tag changes and deduplicates data automatically' and 'Accepts friendly concept names or raw XBRL tags' — behavioral details that go beyond 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?

Three sentences, front-loaded with core purpose. Each sentence adds information: functionality, input flexibility, and automatic processing. No fluff.

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 output schema present and rich parameter descriptions, the description covers the essentials: what it returns (historical data), how to specify inputs (friendly/raw), and dependency on search_concepts for discovery. Missing explicit mention of response structure but output schema covers that.

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 all 5 parameters (100% coverage). The description adds context about friendly-name resolution and historical tag changes that relates to the 'concept' parameter, but doesn't meaningfully enrich parameter meaning beyond 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?

States 'Get historical XBRL financial data for a company' — a specific verb and resource. Mentions it accepts friendly names or raw tags, which clarifies scope. However, it doesn't explicitly contrast with sibling tools like secedgar_get_snapshot, so it's clear but not fully differentiated.

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?

Only hints at discovery via secedgar_search_concepts for friendly names. No explicit when-to-use vs alternatives (e.g., when to choose this over secedgar_get_snapshot). Lacks guidance on when not to use this tool.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) establish the safety profile, and the description layers on consequential runtime behavior on top: stable gap-free paging via returned next_offset, automatic registration as df_<id> when a canvas is available, and a two-month reporting lag. It also flags the non-obvious dating semantic — results are as of report_period_date, not today.

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?

Dense but efficient — input disambiguation, direction contrast, output fields, paging contract, and timing each appear exactly once with zero redundancy. It sits at the upper bound of skim-ability and loses one point to a posture that front-loads the core contrast and fits the remaining caveats in a tighter tail.

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 5-parameter tool with three input aliases (ticker, series ID, CIK), a paging protocol, a dataframe registration behavior, and time-dependent semantics, the description closes every gap: the multi-series trust case, the ordering contract, the orphan-period caveat, and the cross-reference to secedgar_company_search for valid series IDs. An output schema exists to document return values, so the narrative can focus purely on caller-relevant behavior.

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 baseline of 3 applies; the description doesn't lose points for missing parameter docs. However, the rich dataset semantics it explains (lag, dating, one-report-per-series) speak to overall behavior rather than adding meaning to individual parameters, which the per-param schema descriptions already cover thoroughly.

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?

Leads with a specific verb and resource — 'List what an ETF or mutual fund holds' — and pins it to the SEC NPORT-P report. The very first sentence frames the sibling ownership tools as the 'opposite direction,' unambiguously separating this from secedgar_get_institutional_holdings and secedgar_find_holders in a 15-tool namespace.

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?

Names the alternatives explicitly with the condition that selects this tool: 'secedgar_get_institutional_holdings and secedgar_find_holders answer who owns a company, this answers what a fund owns.' It also gives a concrete when-not-to-use rule for registrant trusts with multiple series, telling the agent to pass a ticker or series_id without guessing a name.

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, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context: it explains that the inline list is a preview capped at limit, that the full set is materialized as a dataframe when a canvas is available, and that filings are scanned newest-first. It also clarifies the scope of transaction types (nonDerivative vs derivative). The only minor gap is not explicitly stating that the tool is read-only, but annotations cover that.

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 but well-structured, front-loading the core purpose and return fields before diving into usage nuances. Every sentence adds value, though it is slightly long. The SQL example and sibling reference are useful but could be trimmed without losing essential information. Still, it's efficient for the complexity it covers.

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 (3 params, output schema, canvas integration, sibling tools), the description is remarkably complete. It covers what the tool returns, how to use the dataframe for aggregation, when to use an alternative, and the filtering semantics. The output schema exists, so return values are already documented. 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 well. The description adds extra meaning by explaining the transaction_type filter semantics (e.g., 'purchase' = open-market buys code P, 'sale' = open-market sells code S, 'all' includes grants, awards, exercises, gifts) and clarifies that ticker_or_cik refers to the issuer, not the reporting person. This goes beyond the schema's basic 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 clearly states the tool fetches Form 4 insider transactions by parsing SEC EDGAR ownership XML, enumerates the exact data fields returned (reporting person, relationship, date, type, shares, direction, price, post-transaction ownership), and distinguishes it from sibling tools like secedgar_search_filings. The verb 'Fetch' plus the specific resource 'Form 4 insider transactions' makes 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 tells when to use this tool versus alternatives: 'Use secedgar_search_filings with forms=["4"] for broader date-range queries or to search across all companies.' It also explains the canvas materialization and how to query the resulting dataframe with secedgar_dataframe_query, including a SQL example. This is exemplary 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?

Annotations already mark the tool as read-only, open-world, and idempotent, but the description adds substantial behavioral context: ambiguous-name candidates are returned rather than guessed, sub-lines are consolidated by default, pagination is stable via next_offset, and the full holdings set is materialized as a dataframe when a canvas is available. It also discloses the $100M exemption that can lead to missing filings. 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 long but every sentence earns its place given the tool's complexity and five parameters. The purpose is front-loaded, and later sentences add non-redundant operational detail: pagination, consolidation, dataframe materialization, exemptions, and sibling routing. Nothing feels like filler or repetition of the schema.

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 enumerate return fields, and it still covers everything else an agent needs: what data is returned, how paging works, how consolidation behaves, how to run reverse queries, how to analyze the full result set, and a known exemption that can affect expectations. It is complete for a complex data-fetching tool with five parameters and no enumerated values.

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

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

Schema coverage is 100%, but the description adds real semantic value on top of every parameter: ticker_or_cik is clarified as the institutional filer, not the portfolio company, offset explains next_offset and gap-free paging, consolidate distinguishes raw filing rows from summed distinct positions, and quarter maps reporting periods to filing windows. This exceeds the baseline for fully documented schemas.

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?

Opens with a specific verb and resource: 'Fetch 13F-HR quarterly institutional holdings by parsing the SEC EDGAR information table XML.' It clearly distinguishes itself from the reverse-direction sibling secedgar_find_holders and from broader search. An agent can tell exactly what this tool does and how it differs from related 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?

Provides explicit when-to-use and when-not-to-use guidance: use secedgar_find_holders for the reverse direction, secedgar_search_filings for broader search, and secedgar_dataframe_query for aggregated querying. It also warns that passing an issuer ticker like AAPL is a common mistake and points to the correct alternative. This is exemplary routing 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?

Annotations cover readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is already known. The description adds valuable behavioral context: that the full filtered set is materialized as a dataframe when it exceeds the inline limit, that date windows page into the older archive, and that press releases ride as EX-99 exhibits rather than the primary document. These details go beyond what annotations provide. It lacks exhaustive disclosure (e.g., what the output schema looks like), but given the presence of an output schema and annotations, a 4 is warranted for the meaningful additions without contradiction.

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

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

The description is a single dense paragraph and is front-loaded with the purpose, with the most meaningful scoping detail (item codes) stated early. It uses concrete examples efficiently. It is longer than a minimal description, but every sentence adds new information (e.g., date-regime changeover, dataframe materialization, EX-99 note). Slight clutter in the first sentence's long list of examples, but it earns a 4 for force and efficiency without being bloated.

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 moderately complex: it has 5 parameters, a nested items enum, and an output schema. The description closes the gaps that the schema alone leaves open—how item codes relate to 8-K scoping, the changeover date, paging behavior for old filings, and the return context (dataframe for analysis). Given the output schema exists and the description covers the behavioral edge cases, nothing an agent needs to call this correctly is missing. It is complete for its complexity.

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 each parameter. But the tool description and param descriptions add significant value: they explain the pragmatic meaning of 'items' (decoding example codes and overlap between regimes), clarify the comparative semantics ('Ticker is the exact lookup; name search matches current and former names'), and detail the archive-paging behavior of date filters. This is not repetition—it extends the schema with real-world usage notes, so it earns a 5 despite the high schema coverage baseline 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 uses a specific verb ('Retrieve'), a clear resource ('a company's 8-K filings'), and a differentiator ('with their item codes decoded'). It explicitly distinguishes this tool from siblings like secedgar_search_filings and secedgar_company_search by noting they cannot see item-level scoping. The first paragraph crisply states the tool's purpose and names the exact functionality, making the boundary 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 gives excellent usage guidance: it says 8-K item codes are how material events are scoped, it excludes alternatives ('filtering by them is narrower than any form-level filter in secedgar_search_filings or secedgar_company_search'), it names the sibling for fetching documents (secedgar_get_filing), and it explains the dual numbering regimes, including when to pair codes across the 2004-08-23 changeover. This is explicit when/when-not guidance with named 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses meaningful behavior: it reads the companyfacts payload once, applies the same frame dedup and tag priority as secedgar_get_financials, reports duration vs point-in-time values differently, and lists missing concepts under gaps with tried tags rather than zero-filling. 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 but every sentence adds distinct value: purpose, efficiency rationale, consistency guarantee, period behavior, gap handling, and routing to alternatives. The main purpose is front-loaded in the first sentence, and there is no filler.

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 snapshot tool with a rich schema and output schema, the description covers purpose, alternatives, data semantics, missing-value behavior, and consistency guarantees. Nothing an agent needs to call it correctly is missing.

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 documents all three parameters with 100% coverage, including detailed notes on taxonomy and period_type. The description adds context about snapshot semantics but does not add parameter-specific meaning beyond the schema, so the baseline 3 applies.

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 explicitly distinguishes itself from siblings by saying it replaces a run of secedgar_get_financials calls and by routing secedgar_compare_companies for side-by-side comparisons.

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 gives concrete when-to-use guidance: use this when the question is 'what do this company's financials look like right now', and explicitly names alternatives: secedgar_get_financials for a full time series of one concept, secedgar_compare_companies for side-by-side. This leaves no ambiguity about selection.

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 agent knows this is safe to call repeatedly. The description adds the 'empty search with no filters returns the full catalog' behavior, which is helpful context for expected output volume. It doesn't describe pagination or size limits, but for a catalog lookup tool the annotations cover the safety profile; 3 reflects the modest additional disclosure.

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 no filler: the first states the verb and scope, the second names the sibling tools and the reverse-lookup use, the third notes empty-search behavior. Slight room for improvement: the sentence about 'Usability' could be trimmed, but it's information-dense and front-loaded. Loses a point for slight denseness but not for waste.

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 an output schema exists (return format is documented separately), the description covers the key use case: discovering friendly names before calling get_financials or fetch_frames. It explains the search mechanisms and empty behavior. Missing pagination/limit details are minor for a search catalog tool with an output schema; 4 reflects adequate completeness with a small gap.

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 three parameters, including enums with per-item explanations (e.g., balance_sheet covering position items with instant periods). The description adds the reverse-lookup example ('NetIncomeLoss' maps to net_income) which clarifies search semantics beyond the schema's substring description. This adds value but doesn't need to carry the full parameter burden; 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?

States a specific verb+resource purpose: search XBRL financial concepts by keyword, statement group, or taxonomy. Clearly distinguishes itself from siblings by naming two specific consumers (secedgar_get_financials, secedgar_fetch_frames). Goes beyond a generic greeting to explain what the search returns and the reverse-lookup capability.

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 when-to-use guidance: 'Use before secedgar_get_financials or secedgar_fetch_frames to discover the right friendly name'. This positions it as a discovery prerequisite relative to its likely siblings. Confirms the empty-search behavior (returns full catalog) without exclusions. The when-not scenario isn't stated, but the positive guidance is specific and directional.

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 adds rich behavioral context beyond the annotations: the EFTS index floor, the pre-2001 local scan costing a few seconds at a ~5s rate-limit cap, the 50-document boundary, and the split/merge behavior for ranges crossing 2001-01-01, including source tagging per row. The sort and offset parameters also disclose ordering and pagination limitations in detail. This is exactly the kind of behavioral 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 top-level description is three dense sentences with zero wasted words: one for overall scope and coverage, one for pre-2001 local behavior, one for supported syntax. It front-loads the main purpose and defers nuance to follow-up clauses. The parameter descriptions are longer but justified by 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?

For a search tool with this much complexity (mixed eras, local vs. index serving, sort quirks, pagination edge cases), the combined description and schema cover everything an agent would need to call it correctly. The output schema is present, so return values don't need to be explained in the description. No gaps are apparent.

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 top-level description mostly restates what the query parameter already documents (exact phrases, boolean operators, wildcards, ticker:/cik: targeting). It adds context about pre-2001 local scanning, but that is more behavioral than semantic—it doesn't meaningfully change how parameters should be filled beyond what the schema already says.

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: 'Search EDGAR filings since 1993.' It then clarifies the exact coverage split (full-text 2001–present, archive pre-2001) and the supported query features. This makes it clearly distinct from sibling tools like secedgar_get_filing (retrieve a single filing) and secedgar_company_search (find 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 and parameter docs give strong when-to-use guidance, such as 'A date range alone is not a valid search; pair it with forms or entity targeting' inside the query parameter, and explicitly routes one use case to a sibling: 'Use secedgar_get_insider_transactions to retrieve parsed ownership XML.' It also explains the pre-2001 entity-scope requirement. The only missing piece is a broader comparison to other siblings, but the guidance is clear enough.

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