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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds useful behavior: period formats, that CY2024Q4I is required for instant balance-sheet items, and the default return rule (top limit by value unless companies filters). It omits error handling, rate limits, and authentication details.

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?

Single tightly written paragraph, front-loads purpose, then period formats, then filter and default return behavior. No redundant or filler sentences.

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 7-parameter read-only comparison tool with no output schema, the description covers purpose, period formats, filtering, and default return ordering adequately. It leaves output structure and taxonomy/unit nuances to the schema, but core invocation requirements are clear.

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 57%, and the description adds meaning beyond the schema for period syntax, tag examples, companies filtering, and limit/order return behavior. It does not clarify unit, taxonomy, or order defaults, which remain schema-only.

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: comparing one XBRL concept across all reporting companies for a calendar period. It gives concrete examples (rank by revenue for CY2024; compare specific companies) and distinguishes cross-company scope from siblings like get_xbrl_concept. 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?

Provides clear context: use for cross-company comparison of a single XBRL concept, with examples and period syntax. It explains filtering behavior via companies or the default top-limit ranking. However, it does not name alternatives such as get_xbrl_concept or get_financials, nor state 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 already carry the full safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is low. The description adds the data-provenance detail ('from SEC EDGAR submissions') and the scope of returned fields, though it says nothing about pagination, freshness, or rate limits.

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

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

Two sentences, zero waste, with the resource/scope front-loaded and the usage cue at the end. Nothing extraneous or duplicated.

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

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

With no output schema, the description takes on the burden of describing the return payload and does so thoroughly via the field list. An agent has enough to decide whether the tool returns what it needs before calling.

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?

There is only one parameter and schema coverage is 100%, so the schema already documents the accepted forms (ticker/CIK/name) and only 3 is warranted as a baseline. The description adds no semantics beyond what the schema's parameter description already states.

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 ('Company profile from SEC EDGAR submissions') and enumerates the concrete payload (name, tickers, SIC, EIN, former names, latest 10-K/10-Q). This clearly separates it from siblings like search_company or list_filings without the agent opening any 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?

'Use it to orient before deeper research' gives clear when-to-use context for this lookup-style tool. It does not, however, name the alternative (search_company) for ambiguous inputs or state when-not to use it, so it stops short of full 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 already declare the safe-read profile (readOnly, idempotent, non-destructive), so the bar is low, yet the description adds real behavioral detail: output is clean text with aligned tables, long text is paged, and next_offset is returned for continuation. It does not mention rate limits or auth, but the paging and format disclosure are genuine value-add.

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 the core action and format, then identification, then section extraction, then paging. Dense but every clause earns its place; the section examples are long but load-bearing.

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?

No output schema exists, but the description supplies the return contract (clean text, aligned tables, next_offset for paging), which is the key missing piece. For a six-parameter zero-required read tool it is nearly complete, with only edge cases like precedence when both url and company are supplied left unstated.

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 67% schema coverage the description meaningfully compensates: it enumerates real section ids with human labels ('1' Business, '1A' Risk Factors, '7' MD&A, etc.) including 10-Q variants, which the terse schema entry ('Item id to extract') does not, and it explains the max_chars/next_offset paging contract. The `offset` parameter itself is left unexplained, keeping 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?

States a specific verb (Fetch/Read) and resource (an SEC filing's primary document) and adds the exact transformation applied (HTML converted to clean text, tables preserved as aligned rows). This clearly distinguishes it from siblings like list_filings, which enumerates filings rather than reading one.

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 identification routes (a www.sec.gov/Archives `url` from list_filings, or `company` + `accession`) and ties itself to the list_filings sibling. It stops short of stating when NOT to use it or how it differs from get_financials/get_xbrl_concept for structured data, so no explicit exclusions are present.

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 unsurfaced behavior: dedup policy, 'as-filed values from the filing that reported the period', the ordered tag-fallback chain with tags_used reporting, and the quarterly derivation rules (cash-flow quarters from YTD; Q4 = FY minus 9M).

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 nearly every clause carries unique information; purpose and grain are front-loaded. It reads as one long block rather than separated sentences, which slightly hurts scannability of the derivation rules.

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?

No output schema exists, and the description discharges that burden by naming the returned fields (tags_used), the row grain, the value units, and the period derivation logic. Nothing an agent needs to interpret the 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 75% and the description compensates where it matters most: it explains period_type='quarterly' semantics in depth (derived 3-month values, Q4 derivation) and clarifies raw value scaling (391035000000 = $391.0B), which the schema does not state anywhere.

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 ('Key financial metrics normalized from SEC XBRL companyfacts'), enumerates the exact 15 metrics returned, and pins the row grain ('one row per fiscal period'). The 'normalized' framing implicitly separates it from the raw-concept sibling get_xbrl_concept, so an agent can route without opening schemas.

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 only implied: the tag-fallback and quarterly-derivation notes tell the agent what to expect, but there is no explicit statement of when to pick this over get_xbrl_concept or compare_companies, and no exclusions (e.g. non-XBRL filers, foreign issuers).

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description still adds real context beyond them: it discloses the XML source, the inclusion of Form 4/A, and — most usefully — that `limit` counts filings rather than transactions, which the annotations do not 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?

Purpose is front-loaded and every clause carries information, with the caveat about `limit` counting filings placed as a useful trailing clarification. The long field enumeration is dense but justified since there is no output schema to carry 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?

With no output schema, the description thoroughly compensates by enumerating the returned fields and the buy/sell summary, and the parameters are well documented. What is missing is guidance on when to choose this tool versus assembling insider data from other filing tools, and any pagination/volume 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 description coverage is 86%, so the schema already documents most parameters and a baseline of 3 applies. The description nonetheless adds meaning beyond the schema by spelling out the plain-English meaning of the transaction codes (P/S/A/M/F/G), which the schema only gestures at with an example.

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

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

The description names a precise verb+resource ('Recent insider transactions for a company (issuer)') and pins the exact source (SEC Form 4 / 4/A XML). It enumerates the returned fields, making the tool's scope unmistakable and clearly distinct from every sibling in the 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?

Usage is only implied — the tool is obviously the direct path for insider trades, but the description never states when to prefer it over siblings like list_filings plus get_filing_document, nor any prerequisites. The one routing hint ('use search_company first if unsure') lives in the schema, not the description.

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 the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint). The description adds non-trivial behavior beyond them: results are 'newest first, deduped by period,' and framed_only filters to one-fact-per-calendar-period values for the cleanest time series. It stops short of covering pagination or the source API's quirks, so not quite a 5.

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 the core purpose, followed by routing and the framed_only behavior. Every sentence carries distinct information with no redundancy.

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

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

With no output schema, the description usefully discloses ordering and dedup behavior for the returned series. For a 7-parameter tool it leaves pagination (limit) and unit-default behavior to the schema, but the essentials for calling it correctly are present.

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 57% (tag, unit, forms, company documented; limit/taxonomy/framed_only not). The description compensates for the most opaque parameter (framed_only) by explaining its semantics and value, and supplies example tags. limit and taxonomy remain unexplained in both places, keeping this 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?

States a specific verb+resource: retrieving all reported values of one XBRL concept for one company. It explicitly differentiates from the sibling get_financials ('Use for any tag not in get_financials') and gives concrete tag examples, so an agent can distinguish it 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?

Names the alternative explicitly ('for any tag not in get_financials') and gives the condition that selects this tool. It also explains when to set framed_only, providing a clear usage rule rather than leaving intent to inference.

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 the safety profile (readOnly, idempotent, non-destructive). The description adds real behavioral context: newest-first ordering, the exact fields per row, amendment inclusion semantics tied to base-form filtering, and automatic fetching of older history pages for pagination.

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 ordering are front-loaded, followed by compact detail on row contents, amendment behavior, and supported forms. Slightly dense but each sentence carries information; the common-forms list earns its place as enum-free 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?

With no output schema, the description steps in to enumerate the returned fields and describe pagination behavior, so an agent knows both what it gets back and how older results are surfaced. Nothing essential for 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 coverage is 71%, and the description compensates by explaining form-type filtering, date-range filtering, and the include_amendments behavior (amendments matched to base forms). It also confirms implicit pagination fetching, though limit/offset themselves are left to 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 (List) and resource (a company's EDGAR filings) with scope (company-level, newest-first) and the primary filtering dimensions. An agent can immediately tell this is the filings-listing tool, distinct from get_filing_document or get_financials.

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

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

The description implies usage through 'filtered by form type and filing-date range' and the common-form list, but never states when to use this versus sibling tools like get_filing_document or get_financials, nor any explicit exclusions. The 'use search_company first if unsure' hint lives in the schema, not here.

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, so the safety profile is covered. The description goes further and discloses the substantive content of the response: dataset ids, coverage caveats, update frequency, and license/commercial-use terms — exactly the caveats an agent needs before relying on the data.

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?

A single front-loaded sentence that names the action, the resource, the related tool, and the payload contents with 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?

There is no output schema, so the description carries the burden of describing returns, and it enumerates the key fields (dataset ids, caveats, update frequency, license terms). It stops short of describing structure (e.g., grouping, ordering, counts), a minor but real 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?

The tool takes zero parameters (empty object schema), so the baseline is 4; there is no parameter semantics to explain and the description does not need to compensate for any coverage 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 ('List') and resource ('state business-entity registries'), and ties it directly to the sibling tool lookup_business_entity, so an agent can immediately distinguish this reference/catalog tool from the company lookup tools around it.

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 makes clear this is the catalog consulted for what lookup_business_entity covers, including coverage caveats and licensing constraints, which is the key usage context. It does not explicitly state when *not* to use it, but for a zero-parameter reference tool the intended invocation point is unambiguous.

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 the read-only/idempotent/open-world profile, and the description adds meaningful extras: which states list only active entities (NY/OR/PA) vs. include dissolved ones (CO/CT), and that source URLs are returned. Adds real value beyond the annotations, though it doesn't mention rate limits or pagination.

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, each carrying distinct load: search axes, coverage/active-state nuance, and return fields plus the sibling pointer. Front-loaded and 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?

With no output schema, the description compensates by enumerating returned fields (name, id, status, type, formation date, jurisdiction, addresses, registered agent, source URLs). Combined with coverage notes and the list_supported_states pointer, an agent has what it needs to call 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 already high (~83%), so baseline is 3. The description adds semantics on the active_only behavior by tying it to which states include dissolved entities, and clarifies the entity-name/state-id search axes beyond the schema text.

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 (search) and resource (Secretary of State business-entity registries), scopes it to name and/or state entity id, and enumerates coverage. It is clearly distinguishable from siblings like search_company by its official-registry framing.

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?

Says use for private companies, subsidiaries, LLCs, and legal-name verification, and routes the agent to list_supported_states for coverage. Clear when-to-use, though it doesn't explicitly state when to prefer search_company or get_company_profile over this.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower, yet the description still adds real behavior: matching is fuzzy, a match score of 100 means an exact ticker hit, and the corpus is limited to companies with a listed ticker from company_tickers_exchange.json. That source limitation is a genuinely useful scope disclosure not present in 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?

Two sentences, zero filler, front-loaded with the action and immediately followed by the return contract. Every clause (fuzzy, CIK, match score, source file) carries information an agent needs.

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

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

With no output schema, the description correctly enumerates return fields (CIK, name, tickers, exchange, match score) and names the data source and its coverage boundary. It stops short of explaining limit behavior or what an empty/low-score result means, which are the remaining gaps for a two-parameter search tool.

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

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

Schema description coverage is 50%: the query parameter is documented in the schema with the same ticker/name examples, while limit (1-25, default 5) is undocumented in both schema and description. The description adds only the fuzzy-matching nuance for query, so it neither compensates for the undocumented limit nor goes 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+resource ('Find SEC-registered public companies') plus the accepted key types (ticker or name, fuzzy). It also distinguishes itself from siblings by noting the returned CIK is 'the SEC id used by every other tool', which positions it as the lookup entry point relative to get_company_profile and lookup_business_entity.

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

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

The description implies the correct workflow by explaining that the returned CIK feeds every other tool, so an agent can infer this is the search step preceding profile/filing calls. It does not, however, explicitly state when to prefer it over lookup_business_entity or get_company_profile, so the alternative-selection guidance is inferred rather than stated.

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