beatandraise.com SEC Filings

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

Annotations only declare readOnly/idempotent/openWorld; the description goes well beyond them by defining the ref character grammar (<accession>/<filename>@<start>+<len>), the [calc: ref:..., ref:...] convention, the ~200 KB input ceiling, and the full failure taxonomy (rounded, mismatch, bad_ref, not_derivable, unsourced_numbers) with what each means. An agent knows what the tool will and won't accept before calling.

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?

Purpose is front-loaded in the first sentence, followed by example-driven syntax, return codes, and a closing instruction — logical order, no filler. Some length is unavoidable for the citation grammar, though the indented inline examples read slightly like formatting artifacts rather than tight prose.

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?

An output schema exists, so return-value explanation isn't strictly required, yet the description still covers input format, failure semantics, size limit, and the follow-up use of linked_text/footnotes. For a one-parameter read-only validator, 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 schema is a bare {text: string} with 0% description coverage, so the description carries the whole burden — and does: it specifies the in-text citation syntax, both ref forms, and the max ~200 KB size. That is more than enough for the single required parameter.

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 names a specific verb and resource — check every number in a draft against the filing characters it cites — and adds the linking outcome. It is immediately distinguishable from verify_figure (single figure check) and verify_quote, which it implicitly routes away from by naming them as ref sources.

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 prescribes the exact workflow: write citation refs after each figure, take refs from list_figures or verify_figure, use [calc: ...] for derived numbers, fix all failures before presenting, then use linked_text/footnotes. That is explicit routing and a clear when-to-call. It stops short of stating any exclusion or when-not-to-use case, so it falls just short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds genuine domain context: SIC fields appear only 'when known', individuals and most funds have no SIC, SIC is not GICS, and succession_filing is limited to 8-K12B/8-K12G3 from the last five years.

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?

Front-loaded with the core lookup purpose and well organized into paragraphs by concern. It is somewhat long and spells out return fields even though an output schema exists, which is mildly redundant but still aids interpretation.

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?

An output schema exists, yet the description still explains the conditional fields (SIC, fiscal_year_end, state_of_incorporation, succession_filing) that an agent would otherwise misread. Nothing needed to invoke 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?

Schema coverage is 0% and the schema is just an untyped string, so the description carries the load: it defines CIK as Central Index Key and gives both accepted zero-padded and unpadded forms ('0000320193' or '320193'). That is meaningfully 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?

States a specific verb and resource ('look up a company by CIK') plus the exact fields returned, and implicitly separates itself from search_companies, which is named as the route for name-based or predecessor-CIK lookups.

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?

Usage is clear: call this when you already hold a CIK, and follow search_companies when the history sits under a predecessor CIK. No explicit exclusion is stated for the name-search case, so it stops just short of full when/when-not 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile needs no restating. The description nevertheless adds real behavioral context beyond them: the return format (markdown by default, raw HTML when get_markdown=False), a citation convention (first line is the beatandraise.com viewer link), and the accepted URL shapes. It does not say what happens with very large documents (truncation, size limits), which is the one missing behavioral trait.

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?

Purpose and the sibling exclusion are front-loaded in the first two paragraphs, with format and identification guidance following. The Args block restates parameter names, but given 0% schema coverage that restatement earns its place. Minor slack in phrasing such as 'a fraction of the document, with a link highlighting it'.

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 fetch tool with an output schema, the description covers what an agent needs: how to identify the document, the two output formats, and the citation convention. The remaining gap is operational behavior on large filings (pagination, truncation, response size), which matters for whole 10-K retrieval and is neither in the description nor the annotations.

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 0%, so the description must carry the whole burden, and it largely does: every parameter is named with meaning, an example value (cik "0000320193", filename "ef20060722_8k.htm"), a default (get_markdown True) and the fallback behavior for cik ('found from the accession number when left out'). It also documents the two mutually exclusive identification modes (accession_number+filename vs url). The one gap is that it never states as a hard requirement that one of those two modes must be supplied, leaving all-optional params ambiguous.

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 filing document's content from storage') and immediately distinguishes itself from the closest sibling, get_filing_item, by explaining that the sibling returns a single Item with a highlighting link. An agent can tell which tool to call without inspecting either 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?

It states exactly when to use the sibling ('For one section of a 10-K, 10-Q, 8-K or 20-F ... use get_filing_item instead') and when to use this tool ('to read the actual text of a whole 10-K, 8-K, exhibit, or any other filing document'). The alternative and the selection condition are both explicit, including the negative scoping note that the url is 'not a company website'.

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, non-destructive, open-world behavior, so the safety profile is covered. The description adds real value beyond that: it discloses the shape of content_object (filename, doc_type, description, sequence, markdown availability), the citation URL pattern, and the XBRL R*.htm caveat.

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?

Front-loaded with the core purpose, then supporting detail about content_object and citation. Dense but every sentence carries information; minor redundancy between the inline Args note and 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, return values need not be explained, yet the description still summarizes content_object fields usefully. Annotations cover safety, and the parameter example fills the 0% schema coverage gap, leaving little an agent would need to infer.

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 0% with one required parameter, so the description must compensate – and it does by giving the expected accession_number format with a concrete example ('0001140361-26-006577'). That is meaningful guidance beyond the bare string type in 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?

States a specific verb and resource ('Get full filing metadata') and immediately clarifies the scope by naming the key payload, content_object. It effectively differentiates itself from get_filings (list) and get_document (read one doc) by describing what content_object contains.

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 routes the agent to get_document for reading a document and to list_filing_tables for identifying XBRL table pages, which is strong when-to-use guidance. It does not explicitly contrast with get_filings or search_filings for locating a filing, leaving that inference to the agent.

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 establish readOnly/idempotent/non-destructive, and the description still adds real behavioral disclosure: the APPROXIMATE fallback when a heading isn't found, what that fallback span contains, and the highlight_url in the first lines for citation. That is context an agent cannot get from structured fields.

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?

Well front-loaded — size comparison and fallback caveat come before the arg list, which is the right order. Some prose ('That span contains the item if the filing has it: search within it') is slightly wordier than needed, but nothing is 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 4-param read tool with an output schema, everything an agent needs is present: when to pick it, fallback behavior, and how to interpret the returned header lines. Return-value structure is correctly left to the output schema.

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

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

Schema coverage is 0%, so the description carries the full burden and does: accepted item formats ('1A', '7A', '2.02', '16G', or names), the 20-F remapping (Risk Factors in 3.D, MD&A as Item 5), part semantics with the bare-number default, and get_markdown's default and False 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?

States a specific verb+resource ('Read one Item of a 10-K, 10-Q, 8-K or 20-F') with concrete examples (Risk Factors, MD&A) and immediately distinguishes itself from get_document by size. An agent can tell exactly what this returns versus a whole-filing read.

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 frames the choice ('instead of the whole document'), quantifies the savings ('5-15% of the filing'), and routes non-applicable cases elsewhere: 'other forms have no Items: read them with search_document or get_document'. Alternatives and exclusions are both named.

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/openWorld, and the description adds substantial non-obvious behavior: dedup plus newest-first ordering, the ~2% unreliable headline cases with a verify_quote warning, the exhibits-only 8-K caveat, and a 500,000-character page cap that silently lowers limit. These are exactly the traits structured fields cannot 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?

Front-loaded with purpose and return shape, then args, which is the right order, and the length is defensible for ten undocumented parameters. Still, some passages are heavier than needed, such as the long worked headline example and the EX-5.01 exhibit-title sample, which could be trimmed without losing guidance.

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 everything an agent needs to call this correctly: what is returned, how documents/items/headlines are represented, citation construction, pagination, and each parameter's semantics. An output schema exists, so the extra return-value detail is bonus rather than filler.

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 0%, so the description carries the full burden and does: it documents all ten parameters with formats, examples, defaults, bounds (limit 1-100, 25 with include_item_text; item_text_chars 1,000-100,000), enum-like value lists for item, and the interaction between item/include_item_text/item_text and form.

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+resource and scope: 'Query SEC filings by form type, date range, CIK and/or 8-K item,' and immediately states the return shape ('deduplicated filing metadata sorted by filing date'). It also routes to the right follow-up tools (get_document, list_filing_tables), so an agent knows exactly what this call produces versus a detail/document fetch.

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?

Gives concrete when-to-use guidance for the tricky parameters ('Use it instead of reading 8-Ks one by one to find every director change this week') and when to include item text. It also explains default behavior for from_date and item. It never explicitly contrasts with the sibling search_filings, which is the one likely confusion point left unaddressed.

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 supply the safety profile (readOnly, idempotent, openWorld), and the description adds genuinely new behavior: filings returned newest first, statements NOT merged into a single table, repeated periods and label/scale drift between filings, XBRL coverage phase-in dates, tag availability lagging one night after filing, and enlarged responses when include_tags is true.

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?

Purpose and the sibling comparison are front-loaded, and the Coverage and Args blocks are cleanly separated. It is long (~500 words), but nearly every sentence carries actionable information given 8 undocumented parameters; a few clauses on include_tags could be tightened.

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?

Despite having an output schema, the description still explains enough return shape (per-filing statements, lines with concept/members/unit/ref/highlight_url) for the agent to plan usage, and it covers the main failure modes — missing pre-2009 data, missing refs before mid-2019, missing tags on new filings.

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 0%, so the description must carry all parameter meaning — and it does: defaults and maxima for period/limit, the valid statements enum values, the YYYY-MM-DD format for before, fiscal-vs-calendar year with a Medtronic example, the absence of a Q4 filing, and the cost tradeoff of include_tags.

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 and resource ('A company's financial statements from its last several 10-Ks or 10-Qs, in one call') and explicitly contrasts itself with the sibling it resembles ('instead of calling get_financial_statements filing by filing'). An agent can distinguish the two tools without opening either 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?

Names the alternative (get_financial_statements) and the condition selecting this one (trend analysis across years/quarters). It also routes negative cases: pre-XBRL reports go to get_filing_item, and foreign filers' quarterly 6-K data is declared out of scope.

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/idempotent, and the description layers on substantive behavior the annotations cannot express: XBRL coverage boundaries by company size and date (mid-2009 / mid-2010 / mid-2011), the night-after-filing lag for tags, missing refs for dash (zero) lines and pre-mid-2019 filings, and the larger response size with include_tags.

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?

Front-loaded with purpose, then workflow, then coverage caveats, then args — the ordering is sensible. The include_tags block is long and paragraph-dense, though nearly every clause carries information an agent would otherwise have to discover by error.

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 a simple 3-parameter read tool with an output schema, the description covers the remaining unknowns: coverage limits, failure mode for early filings, tag latency, and the outbound escalation path for older years. Nothing an agent needs to call it correctly or interpret an empty result 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 coverage is 0%, so the description must carry the load, and it does: cik gets a concrete example, accession_number is scoped to 10-K/10-Q, and include_tags is explained in depth (concept + axis members + unit, full-unit values, printed text, ref for check_citations, highlight_url) along with when it is unavailable. This is meaning well beyond the bare boolean default in 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?

Specific verb plus resource ("Extract structured financial statements from a 10-K or 10-Q filing") followed by an explicit enumeration of what comes back (balance sheet, income statement, cash flow, equity, comprehensive income). It is clearly distinguished from siblings get_filing_item (raw Item 8 text) and get_financial_history.

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?

States the prerequisite workflow explicitly: find an accession number with get_filings, then pass it here. It also names the alternative for out-of-coverage filings ("read a 10-K's Item 8 with get_filing_item") and advises reducing statements/filings when include_tags is set.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real operational context beyond that: flags are "never corrected," ~1% cover disagreement, header-only dates mostly pre-2011, and Q4 has no standalone 10-Q. However it does not disclose result-size or performance characteristics for large windows, and its value here is mostly data semantics rather than tool 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?

Front-loaded with the one-line purpose, then usage, then edge cases, then args – a sensible order with no filler. It is dense and field-name-heavy (irregular_quarter, fy_mismatch, duplicate_report), which costs some readability, but essentially every clause carries information an agent would otherwise have to guess.

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?

An output schema exists, yet the description still previews the notable return fields and, crucially, their caveats (period_mismatch resolution, transition filings, amendment_only, first). Combined with the exclusions and pagination semantics, an agent has everything needed to call this correctly without further exploration.

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 0%, so the description must carry the load, and the Args block does: cik with an example and a pointer to search_companies, from_date/to_date with an explicit YYYY-MM-DD format, fiscal_year with an example, and limit with its 1-400 range, default 40, and the non-obvious "newest N, returned oldest first" semantics. That last detail is unavailable anywhere in 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?

First sentence gives a specific verb and resource ("Get a company's fiscal calendar") and immediately defines the unit returned: one row per quarter with its own dates. That scope clearly separates it from siblings like get_financial_history, get_financial_statements, and get_filings, which do not carry fiscal-period dates.

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 routing: "Use it whenever a question names a fiscal period" with three concrete query examples, plus the reason alternative guessing fails (fiscal years ≠ calendar years, 52/53-week weekday drift). It also states the exclusion ("10-K/10-Q filers only: a foreign filer (20-F, 40-F) has no quarterly calendar here") and points to search_companies for the CIK.

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 annotations, the description discloses that the question is recorded along with all call arguments and is used to prioritize what to add, plus that results are ordered most-relevant-first. It does not describe the shape of the returned entries, but an output schema exists to 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?

Front-loaded with purpose, then triggers, then parameter guidance — a sensible order. The clause about recorded arguments and the support-email sentence are slightly rambling for a two-param tool, though the recording note does carry real information.

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

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

For a simple two-optional-param helper with an output schema, nothing material is missing: purpose, triggers, both parameters, result ordering, and privacy/recording behavior are all covered.

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

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

Schema description coverage is 0%, so the description must carry the full burden: it defines question as the user's need in their own words with concrete examples ("institutional ownership of SPY", "Risk Factors of a 40-F") and tool_name as the tool that fell short, with a sample value. Both optional params are fully explained.

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?

"What the beatandraise.com tools cover, where they stop, and what to use instead" gives a specific verb+resource (coverage/limits guidance) that no sibling tool provides. It is immediately distinguishable from the lookup tools in the sibling list.

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 trigger conditions are listed: a tool returned nothing, returned an error, returned less than needed, or no tool exists for the request. This is exactly the when-to-use guidance an agent needs to route here instead of retrying a failing sibling.

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 this is a safe, read-only, idempotent, non-destructive, open-world operation. The description adds substantial behavioral detail beyond that: parsed XML versus text fallback, one row per entry, units in thousands versus dollars depending on filing date, line-based paging for text results, period_note behavior, and SIC classification coverage.

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 and well structured, moving from purpose to return format to edge cases and then arguments. It is longer than strictly necessary, especially the SIC coverage statistics and get_company cross-reference, but those details are relevant and not 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?

Given the tool's complexity, four parameters, 0% schema description coverage, and the presence of an output schema, the description is complete enough for an agent to call it correctly. It covers fallback text-format filings, paging behavior, period semantics, and the meaning of SIC coverage.

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 0%, so the description must carry all parameter semantics. It does: cik is the filer CIK with an example, period means return the most recent 13F filed on or before that date, limit is max holdings per page with range and default, and offset is pagination offset.

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 a specific verb and resource: get parsed 13F-HR institutional holdings for a filer, including the fields returned. It does not explicitly distinguish this tool from the sibling get_institutional_holders, so it falls short of full sibling differentiation.

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 useful conditional guidance for interpreting XML versus pre-2013 text-format 13F filings, including using search_document for text tables and sic_url from get_company for peer comparisons. However, it does not clearly say when to use this tool versus alternatives such as get_institutional_holders, leaving some usage choice implied rather than 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 already declare a safe read-only, idempotent, non-destructive operation, but the description adds substantial behavioral context: default Table I-only output, Table II behavior, footnote inclusion, coverage boundaries, transaction-code meanings, and caveats such as counting RSU vestings once. It also warns about the limitations of plan_10b5_1, which is exactly the kind of nuance an agent needs before interpreting results.

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 purpose and is generally information-dense, but it is long and repeats the coverage_from date in two sections. Most sentences earn their place because the financial/legal caveats are useful, though the length could be trimmed slightly.

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 output schema, and the annotations, the description is complete. It covers data source, coverage period, default versus optional output, transaction codes, footnote behavior, Table II semantics, and interpretation caveats, leaving no critical gap for correct invocation or interpretation.

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 0%, so the description must carry parameter meaning, and it does: every parameter is documented in the Args section, including CIK meaning, date ranges, limit as max filings, offset pagination, and the precise effect of include_table_ii and include_footnotes. This fully compensates for the lack of schema descriptions.

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

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

The description states a specific verb and resource: get parsed Form 4 insider transactions for a company, with source data from Form 4 XML. This is clearly distinct from sibling tools such as get_holdings and get_institutional_holders, and an agent can identify the tool 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 operational guidance for optional parameters, especially when to use include_footnotes and include_table_ii, and explains the coverage start date. It does not explicitly compare this tool to sibling tools or state when not to use it, so it falls short of the highest level.

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 cover safety (readOnly, idempotent, non-destructive), but the description adds substantial behavioral context: response size expectations for holder queries (~5 KB), the effect of detail="full", caveats about 13F data (not deduplicated, options excluded, >100% possible, new positions can be artifacts), and guidance on which fields to read for common questions.

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 well-structured and front-loaded with purpose, use cases, and arguments. However, it includes a lengthy enumeration of return fields (quarters, share_classes, etc.) even though an output schema exists, making it slightly more verbose than strictly necessary. Still, the information is dense and largely earns its place.

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

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

Given the tool's complexity (5 parameters, 13F data domain, output schema present) and the description's coverage of purpose, alternatives, usage scenarios, parameter semantics, caveats, and return field guidance, the definition is complete enough 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 description coverage is 0%, so the description must carry the full burden. It does: company accepts ticker or CIK (with explicit warning it's the company's CIK, not the institution's), quarters range and default, holder can be a name fragment or filer CIK, limit range and default, and detail values with default behavior explained.

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 explicitly states the tool's purpose: 'Who holds a company, from 13F filings: how much of each share class institutions hold, and how that changed quarter by quarter.' It also directly distinguishes itself from the sibling tool get_holdings by specifying that this is the company-side view while get_holdings is the manager-side view.

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 use cases with example questions, tells the agent when to use holder vs. top_holders vs. large_holders_5pct, explains the default lean behavior when holder is provided, and notes when to pass detail="full". It also clarifies that get_holdings is the alternative for manager-side queries.

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, idempotentHint, non-destructive and openWorld, so the safety profile needs no restating. The description adds real substance beyond that: the breadth of the payload (co-issuers, related persons with CRD numbers, sales compensation recipients, filer notes, signatures) and the ordinal ordering of offering_history, which tells the agent the response is a complete single-filing record rather than a summary.

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?

Front-loaded with the action and the key argument, followed by a payload inventory and an args block. The middle sentence is a long comma-and-semicolon enumeration, but each listed field group carries distinct information; only the offering_history gloss is close to excess given an output schema exists.

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 single-parameter lookup with an output schema and full safety annotations, the definition covers the entry path, the identifier format, and the scope of the returned record. The remaining gap is failure/not-found behavior, which is minor here.

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 0%, so the description must carry the parameter, and it does: it names the argument "accession_number" as a Form D accession number and supplies a concrete format example ("0001104659-26-114962"). It still does not say whether the dashed or undashed form is accepted, which keeps it below a 5.

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 line gives a specific verb and resource ("Get one Form D filing in full, by accession number") and immediately attributes the identifier to its sibling search_private_offerings. An agent can distinguish this from search_private_offerings without opening either 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?

Naming "(from search_private_offerings)" makes the intended workflow explicit: search first, then fetch the full record by accession number. There is no statement of when-not to use it or of failure behavior for an unknown accession number, so it stops short of full when/when-not 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 only cover read-only/idempotent/no-destructive safety; the description adds substantial behavioral context beyond that: counts are as-filed and never split-adjusted, rows are ordered oldest-first, one row per class and as-of date, coverage starts in 2009 and only for XBRL-tagged filers, 20-F/40-F filers yield roughly annual windows, filer errors are returned as filed, and split listing depends on a subsequent restatement. That is exactly the kind of non-obvious behavior an agent needs before trusting the output.

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 purpose is front-loaded, but the body is a single dense block of edge-case prose (split detection heuristics, 1000x tag corrections, combined ratios, multi-class member names, 2020 Apple example) with no bullets or grouping, so key calling information competes with domain trivia. Much of it is valuable, but the agent must read the whole wall of text to extract the routing decision.

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 domain-specific historical-data tool this is thorough: it covers coverage window, ordering, multi-class naming, the 'listed' ticker mapping, as-filed fidelity, and error passthrough, and it explains the returned split/restatement fields. With an output schema present, that return-value detail is redundant but nothing an agent needs in order 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?

Schema description coverage is 0%, so the description must carry the burden, and it supplies a brief Args section: CIK with an example, share_class 'as returned in share_class', from_date with YYYY-MM-DD format, to_date as 'Latest as-of date'. This clarifies that filtering is on as-of date rather than filing date, which the schema does not, but it omits the null defaults, gives no format hint for to_date, and the share_class phrasing is self-referential and circular.

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 names a specific verb and resource (share counts over time) and pins the exact data source (cover page of 10-K/10-Q/20-F/40-F, dei:EntityCommonStockSharesOutstanding). It also differentiates from the general filing-reading siblings by stating 'Use this for share-count history, dilution, buybacks and splits instead of reading filings one by one.' No ambiguity about what is returned or where it comes from.

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 enumerates the use cases (share-count history, dilution, buybacks, splits) and tells the agent not to read filings one by one, plus a diagnostic rule: 'a ratio_to_previous far from 1 with no split listed is worth checking in the filing.' However, it never names a concrete sibling tool (e.g. get_financial_history or verify_figure) as an alternative for the same question, so routing is implied rather than 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 already declare readOnly/idempotent/openWorld, and the description adds real context beyond them: pagination at 100 per page, ticker-holding companies ordered first, listed_only defaulting True and what setting it False surfaces (dormant, delisted, asset-backed entities). The caveats that SIC is assigned at registration, is not GICS/NAICS, and is absent for individuals and most funds are exactly the kind of domain trap an agent needs flagged.

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?

Front-loaded with the action and an example code, then the fallback, then caveats, then args. The closing 'Args:' block largely restates the prose above (industry, page size, listed_only), so it is slightly longer than strictly necessary, but nothing is buried or wasteful enough to hinder scanning.

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?

An output schema exists, yet the description still tells the agent the shape of a row and the ordering, and it fully covers the dual-mode input, the drill-down workflow, and the classification caveats. Nothing needed to call this correctly or interpret results 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 0%, so the description must carry the full burden and does: industry accepts either a 3-4 digit code or an industry word, query filters name/ticker with a code, page is 1-indexed at 100 per page, and listed_only's default and effect are spelled out. Each of the four parameters is given meaning the bare schema does not.

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 and resource ('List the companies in an industry') and pins it to the SEC's SIC classification, which separates it from search_companies and list_sic_codes. It also names the exact fields returned (CIK, name, ticker, state, fiscal year end), so an agent knows what it gets 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?

Gives explicit routing: use get_company or search_companies for a company's own code, list_sic_codes for the whole classification, and this tool for the companies in a code. It even handles the unknown-code case by describing the word-lookup fallback on the same tool, then tells the agent to re-call with the returned code.

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 only cover the safety profile (readOnly/idempotent/non-destructive/openWorld); the description adds the domain-critical behavior that figures arrive as unscaled digit strings that must be multiplied by a power of ten, and the rounding constraint that rules out citing 416,161 as $416.9B. Also discloses volume (~2,000 vs ~400) and the hl deep-link construction.

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?

Front-loaded with purpose then a concrete JSON entry example, then the scale rule, then filtering and linking. Slight redundancy between the opening line and 'Each entry is a number with its label', but no sentence is wasted given the 0% schema coverage.

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?

An output schema exists, so return values needn't be enumerated, yet the description still supplies the interpretive layer the output schema can't (units/power-of-ten scaling, column ordering). Combined with filtering and deep-link guidance, an agent has everything needed to call and use the result 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 0%, so the description carries the full burden and does so: cik/filename carry format examples, `near` is defined as case-insensitive substring on the label with realistic examples, and `limit` is given both range (1-2000) and default (300), matching 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?

States a specific verb+resource ('List the numbers a filing document actually states') and immediately characterizes the return unit as a labelled figure with digits stripped of formatting. That framing distinguishes it from list_filing_tables (tables) and search_document (text search) without needing either 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?

Gives concrete operational guidance: use `near` for label filtering, filter mandatory for 10-Ks (~2,000 figures) but optional for press releases (~400), derive scale from label/table heading, assume current-period-first column order but confirm. It stops short of naming alternative tools (e.g. verify_figure) for the case where you already have a number and want to check it.

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 safety (readOnly, idempotent, non-destructive), and the description adds substantive behavior beyond them: items are located by document headings rather than literal string matching, so TOCs and cross-references are never mistaken for sections. It also explains the not_located semantics with concrete causes (Item 1C pre-2023, 10-K/A with only Part III, unreported 8-K items, or missed headings), which no annotation conveys.

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?

Front-loaded with purpose and return shape, then fallbacks and caveats in descending priority — the ordering is correct. It runs longer than most definitions, but nearly every sentence (heading-detection, not_located causes, sibling routing) carries non-redundant information; only the entry-field enumeration slightly overlaps the output 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?

For a one-parameter read tool with an output schema and full safety annotations, nothing an agent needs is missing: valid inputs, sibling routing, not_located interpretation, and fallback behavior are all covered. Return values are explained even though the output schema already exists, which is surplus rather than a 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?

With 0% schema coverage on the single required parameter, the description must carry the load, and it does: it names the valid form types and gives a concrete accession-number example format ("0000320193-25-000079"). It stops short of stating the format rules explicitly (10-digit filer prefix, year, sequence), which would have made it a 5.

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+resource ('List the Items of a 10-K, 10-Q, 8-K or 20-F') and immediately bounds the deliverable: which sections exist and where. It also enumerates the per-entry fields (item, part, SEC title, filer heading, length, highlight_url), so an agent knows exactly what it gets without opening the output 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?

Explicitly routes: 'Read one with get_filing_item' for section text, and 'Other forms (6-K, 40-F, DEF 14A, S-1...) have no numbered Items: read them with search_document or get_document.' It even covers the not_located edge case and states get_filing_item still answers for those, so both the primary and fallback paths are named.

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 establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond annotations: it names FilingSummary.xml as the source, describes one-entry-per-Report behavior, and explains that an empty list typically means no FilingSummary.xml or no indexing yet. This is useful behavioral disclosure, though not exhaustive about return ordering or limitations.

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 action, then explains return shape, canonical types, empty-list semantics, and the single argument. Each sentence adds useful context without wasteful 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 a single required parameter, rich annotations, and an output schema, the description is complete enough to call the tool correctly. It explains the source data, what entries contain, how to use the filename, example canonical roles, and what an empty result means.

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 for accession_number is 0%, so the description must compensate. It does so by defining the parameter as an SEC accession number and providing a concrete example format ('0000320193-25-000079'), which is important for correct invocation. For a single required parameter, this is adequate.

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 and resource ('List every R*.htm financial table in a filing') and clearly explains what is returned: one entry per <Report> from FilingSummary.xml. It also distinguishes itself from get_document by noting the returned filename is what you pass to that sibling, and explains the canonical xbrl_role_normalized field.

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 a clear use case: finding financial tables and locating statements like the income statement across filers via canonical roles. It also explains the empty-list condition, which helps an agent interpret results. It does not explicitly compare itself to list_filing_items or get_financial_statements, but the context is strong enough for a 4.

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 cover safety (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: result ordering (most companies first), a hard cap of 50, the shape of each row, and the volume cost of the no-query path. That cost/benefit disclosure is exactly what annotations can't express.

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?

Front-loaded with the purpose and the return shapes, with no filler sentences. The trailing "Args:" block duplicates the schema's optional query and is the one piece that doesn't earn its space.

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?

An output schema exists, yet the description still tells the agent enough about both return modes to choose correctly and to consume the result. Nothing needed to invoke this tool 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 single parameter has 0% schema coverage, so the description must carry it, and it does: query is a word matched against industry titles, with concrete examples ("software", "bank", "oil", "pharmaceutical"), marked optional, and its absence is defined. It stops short of stating the matching rule (substring/prefix/case), leaving a small ambiguity.

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 and resource ("List the SEC's SIC industry codes") and immediately names the downstream sibling it feeds, list_companies_by_sic. It also explicitly distinguishes SIC from GICS and NAICS, which prevents a whole class of misclassification.

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?

Gives explicit when-to-use branches: with a query you get matching codes ranked by company count; with no query you get all ~440 codes, and it advises "prefer a query." It also routes the agent onward (list_companies_by_sic for a code, get_company for a single company's own code).

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 this as a read-only, idempotent, open-world, non-destructive search. The description adds useful domain behavior beyond annotations, especially the meaning of succession_filing and how predecessor filings may be filed under a different CIK.

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 search behavior and return data, then adds a useful edge-case paragraph. It is longer than strictly necessary, but every section has a clear purpose and the Args block is 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?

An output schema exists, so the description needn't fully document return values, but it still provides helpful context about CIK, names, tickers, and SIC fields. Combined with the successor-filing explanation and parameter details, it is complete enough for an agent to invoke 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 0%, so the description carries the burden and mostly compensates: it explains query as company name or ticker with examples, and limit as max results with range 1–50 and default 10. It could be slightly more precise about matching behavior, but the essential parameter meaning is present.

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 gives a specific verb and resource: search for companies by name or ticker. It also clarifies the return contents (CIK, known names, ticker symbols, SIC code/name) and states its role in finding a company's CIK before using other 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?

It clearly says to use this tool to find a company's CIK before using other tools, which is strong routing guidance among siblings. It also explains the successor-filing edge case and points to search_document for predecessor lookup, though it does not explicitly contrast with similar discovery tools like list_companies_by_sic.

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/destructive=false, yet the description adds real behavioral context: a 12-file cap on the all-documents search, raw-XML handling for XML-only forms, and the per-file source URL for citation. It does not discuss truncation behavior when many lines match, which is the remaining gap.

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?

Front-loaded with purpose and return shape, then scope behavior, then a numbered workflow. The trailing 'Args:' block largely restates the schema, which is mild redundancy rather than noise, but it slightly bloats an otherwise tight description.

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 an output schema, everything an agent needs to call it correctly is present: required vs optional, fallback derivation of cik, scope of the search, result shape, and citation guidance. Return-value detail is appropriately deferred to the output schema.

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

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

Schema coverage is 0%, so the description must carry the burden and it does: it explains accession_number format, comma-separated query semantics (including the comma-in-number rule), that cik is derived when omitted, filename's all-vs-one behavior, and context_lines' 0-50 range with default 10.

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 and resource ('Search within a filing's documents') plus the return shape ('matching lines with context'). It is clearly distinguished from siblings like get_document (retrieval) and search_filings (filing-level discovery) via the workflow section.

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 an explicit three-step workflow naming get_filings and get_filing_detail, plus the key selection rule: omit filename to search all documents, include it to search one. Exclusions and ordering are spelled out rather than inferred.

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/openWorld, so the bar is low, yet the description adds substantial behavior beyond them: relevance ranking, facets by form type and year, excerpt inclusion conditioned on limit<=10, pagination via page=, and a coverage_note in the response. Nothing important about the call's behavior is left implicit.

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?

Front-loaded with what it does, then return shape, then routing, then coverage, then args — a logical order with no filler. The Args block restates some of the body (e.g. limit/excerpts) and the support email adds a little bulk, but the redundancy is mild and aids scanning.

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 query semantics, filtering, result shape, excerpt behavior, pagination, and coverage boundaries, and an output schema exists so return values need no further explanation. Complete enough for an agent to call it correctly on the first try.

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 0%, so the description must compensate and does: it documents all six parameters with examples, including the critical cik-vs-company-name guidance with a worked example and the limit/excerpt interaction that the schema cannot express. This is exactly what a low-coverage schema needs.

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 ('Full-text search across all SEC filing content') and immediately differentiates from siblings: search_document for exhaustive occurrences in one document, get_filings for older filings. An agent can route correctly without opening another 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?

Explicit routing rules: use search_document for every occurrence in one document, get_filings + get_document for pre-2020 filings, and a concrete exclusion list of forms not covered. Also states the non-obvious failure mode (a search for an earlier year returns nothing).

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 this is a safe, read-only, idempotent search, and the description adds substantial behavioral context beyond them: amendments restate the whole form, `total_amount_sold` is cumulative, totals cover the WHOLE match not just the page, dates filter filing date rather than first-sale date, and state/solicited_in never indicate investor location. It also warns that Pooled Investment Fund amount sold can be cumulative subscriptions (e.g. $591 billion for Alexander Series Trust), which an agent could easily misinterpret.

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 the complexity and 23 parameters justify much of the length, and it is organized into purpose, result shape, categories, reading the numbers, and Args. Some material, particularly the long list of real-filing examples and repeated category enumerations, could be trimmed without losing essential guidance.

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 a 23-parameter search with 0% schema description coverage, the description is complete enough for correct invocation: it covers result shape, totals behavior, category vocabularies, amendment semantics, date semantics, amount caveats, and every argument. An output schema exists, so it does not need to explain return values, though it usefully describes the totals structure anyway.

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 0% across 23 parameters, so the description must carry all parameter meaning, and it does: every argument is listed with examples, enum-like values, comma-separated semantics, and edge cases (`recipient` accepts a FINRA CRD like "7691" = Merrill Lynch, `solicited_in` never matches offerings with no paid agent, `q` also matches SPVs named after a company). It even explains the full SEC industry and fund_type vocabularies and issuer-size ranges.

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 Form D filings: private placements and private funds', and scopes it to Regulation D exemptions since 2009. It also explicitly distinguishes this search tool from `get_private_offering` for a single filing, and from `search_companies` when you need an issuer CIK.

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 explicit routing rules: use `get_private_offering` for one filing in full, use `search_companies` to find a CIK before passing `cik`, and use amount filters instead of size filters when looking for smaller raises. It also documents when `max_offering` will never match Indefinite offerings and how `amendments` modes change what is returned.

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, non-destructive and open-world, so safety is covered. The description adds real behavioral context (digit-only comparison, magnitude-blind matching, ranking by exactness and label overlap, 10-match cap, search scope controlled by filename), but a 3 is appropriate because much of the text also repeats what the schema and return contract already 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?

Front-loaded with the core assertion and highly dense, but the matching-rule paragraph is long and repeats the magnitude caveat twice (once in the rules, once in the return section). Slightly verbose for the payload it delivers.

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?

An output schema exists, yet the description still names the return fields and explains how to use highlight_url and interpret found=false, which is exactly the operational guidance needed. Nothing required to invoke or act on results 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 coverage is 0%, so the description carries the full burden and largely does: cik gets a format example, value gets detailed normalization rules and a one-significant-digit caveat, label is explained as a ranking signal, and filename explains its scoping effect. Only accession_number lacks a format example, a minor gap.

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 and resource ("check that a number ... appears in a filing") plus the exact matching semantics. It is clearly distinguishable from siblings like check_citations (citations) and verify_quote (quotes) without opening a 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?

Explicitly states when to use it (before attributing a figure to a filing), what found=false means and how to react (do not attribute; say it was calculated and cite inputs), and how to handle derived numbers. Covers both the positive and negative cases.

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/non-destructive, but the description goes well beyond that: exact-match semantics with whitespace, table-cell, dollar-sign and curly-quote tolerance, occurrence handling guidance, and what found=false plus numbers_elsewhere mean. This is real behavioral context an agent cannot get from 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?

Front-loaded with the core purpose and the usage rule, and the args block is justified here because the schema is bare. It runs somewhat long and restates return values that also appear in the output schema, which is minor 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?

Covers all four required parameters, matching strictness, multi-occurrence disambiguation, and the negative-result path, so an agent can call it and interpret it correctly without further hints. Nothing material is missing even with a 0%-described schema.

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

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

Schema coverage is 0% and the schema has no param descriptions, so the description carries the full burden — and it does: examples for cik and accession_number, guidance on where filename comes from (content_object or a search result, exhibits included), and a 1000-character cap on quote with formatting advice.

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 concrete verb and resource ('Check that a figure or sentence really appears in a filing document') plus the added value (a highlight link), which is enough for an agent to know what it gets. It does not explicitly distinguish itself from the sibling verify_figure, leaving some ambiguity about which one to pick for pure numeric checks.

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?

Gives explicit when-to-use ('Use this before stating any number or quotation from a filing'), explains why a whole-document link is insufficient, and prescribes the correct input shape with examples. It also covers the failure path: if found is false, consult numbers_elsewhere rather than presenting the text as a quote.

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