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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial context beyond them: the paid per-event cost model with concrete price points, the required APIFY_TOKEN, sec.gov rate-limiting at <=5 req/s, expected run duration (5-60 s, up to ~5 min wait), and that unresolvable companies yield error rows rather than failures. This is exactly the extra behavior an agent needs before committing to a paid call.

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 and organized under labeled sections, with every cost/timing sentence earning its place given the paid remote execution. Slight redundancy in the RETURNS section, which restates return-shape detail already carried by the output schema, prevents a 5.

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 9-parameter, paid, remote-actor tool with an output schema, the description covers cost, auth, timing, throttling, error semantics, and sibling routing, which is everything an agent needs to invoke it correctly. The return-value recap is redundant with the output schema but does not leave gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by tying cost to the sizing parameters ('Keep maxFilingsPerCompany, metrics and maxFactsPerMetric small to limit cost') and giving a worked example call with metrics. It stops short of adding per-parameter syntax detail, so 4 rather than 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 and resource ('Bulk export ... of structured SEC EDGAR data') plus scope ('up to 50 US companies in one call') and enumerates exactly what is returned (entity metadata, filings, XBRL facts, text excerpts). It explicitly distinguishes itself from the free single-purpose siblings, so an agent can route correctly 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 an explicit WHEN TO USE section with mode-selection guidance ('filings' vs 'facts' vs 'both'), names the free alternative tools for interactive lookups, and adds a WHEN NOT TO USE section excluding real-time quotes, prices, options, non-US companies and investment advice. Nothing about selection is left 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?

Adds substantial context beyond the annotations: free/read-only GET to data.sec.gov with no token or Apify billing, case-sensitive concept names, and the important gotcha that values are as-reported with duplicates across filings unless dedupe=true. This is exactly the operational detail annotations 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 the core action and modes, then sectioned with RETURNS, WHEN NOT TO USE, COST and EXAMPLE labels that make scanning easy. Slightly verbose: 'free' is stated twice (opening line and COST section), and the RETURNS detail overlaps the output schema, but the density is largely justified for a 10-parameter tool.

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 10-param tool, it covers modes, default behavior, error codes (COMPANY_NOT_FOUND, NOT_FOUND, SEC_FETCH_FAILED), and points to edgar_resolve_company for ambiguous names. Output schema exists, so return detail is bonus 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?

Schema description coverage is 100%, so the baseline is 3. The description still adds value by framing the concepts parameter as the mode selector (omit to list, pass to retrieve) and providing a concrete example payload with limit and fiscalPeriod, clarifying how parameters combine.

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 (get reported XBRL financial data for one company) plus named source (SEC companyfacts API) and examples of concepts returned. It explicitly distinguishes itself from edgar_get_concept_across_companies, which is the closest sibling.

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 via the two-mode breakdown (omit concepts to list, pass concepts for time-series), a WHEN NOT TO USE section routing to edgar_list_filings/edgar_get_filing_document for documents and to edgar_get_concept_across_companies for cross-company comparison. Nothing is left 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 declare readOnly/idempotent/non-destructive/openWorld, but the description adds substantial context beyond them: it is a free, unauthenticated GET to data.sec.gov (no token, no Apify billing), returns a paged payload with named fields, supports an optional ciks filter, and enumerates errors (NOT_FOUND, SEC_FETCH_FAILED). This is rich disclosure an agent cannot get from 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?

Front-loaded with the core purpose, then organized into labeled sections (Period format, Behavior, WHEN NOT TO USE, COST, EXAMPLE) that each carry distinct value. It is on the long side, and the return-field enumeration partly overlaps the output schema, but nothing is wasted 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 an output schema present and annotations covering the safety profile, the description still supplies auth model (no token), cost, error states, period/unit formats, an alternative-routing section, and a worked example. 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?

Schema description coverage is 100%, so the schema already documents all eight parameters, setting a baseline of 3. The description adds value by spelling out period-format semantics ('CY2023' annual, 'CY2023Q2' quarterly, 'CY2023Q4I' instant for balance-sheet items) and unit examples, reinforcing intent beyond the raw schema strings.

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: query one XBRL concept across every SEC filer via the SEC frames API. It names concrete concepts (Revenues, Assets, NetIncomeLoss) and explicitly distinguishes itself from the sibling edgar_get_company_facts, so an agent can route 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?

Provides explicit when-to-use contexts ('screening and peer comparison') with two concrete scenarios, and a dedicated WHEN NOT TO USE section routing to edgar_get_company_facts for single-company history and edgar_list_filings for filings. Alternatives and the conditions selecting them are fully enumerated.

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?

Goes well beyond the annotations (readOnlyHint/idempotent/openWorld already cover the safety profile) by disclosing the no-token free access model, the URL whitelist restriction (only https://www.sec.gov/Archives/), the fact that 10-Ks can exceed 500k chars, and the pagination contract with nextOffset. Enumerated error codes (INVALID_URL, COMPANY_NOT_FOUND, SEC_FETCH_FAILED, etc.) add concrete failure 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 core action, then cleanly sectioned into Behavior, RETURNS, WHEN NOT TO USE, COST, and EXAMPLE. The RETURNS field list and error enumeration partially duplicate the existing output schema, which is the only wasted space; everything else 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 7 params, rich annotations, and an output schema, the description covers the remaining agent-facing gaps: how to identify the document, pagination strategy for very large filings, cost/auth model, URL constraints, and failure modes. An agent can invoke 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 coverage is 100%, so the baseline is 3, but the description adds relational semantics the schema cannot express: documentUrl comes from edgar_list_filings, company+accessionNumber resolves to the primary document unless 'document' names another file, and offset/maxChars drive the paging loop with nextOffset returned. It does not restate types or bounds, correctly leaving those 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 (Fetch), resource (SEC filing document text from EDGAR), and the transformation applied (HTML converted to plain text, character-paged chunks). It is clearly distinguishable from siblings like edgar_list_filings (discovery) and edgar_get_company_facts (structured values), which it names.

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

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

Contains an explicit WHEN NOT TO USE block routing to edgar_list_filings for discovery and edgar_get_company_facts for structured numbers, plus a positive use statement ('Use to read the actual content of a filing'). Two identification paths (documentUrl vs company+accessionNumber) are also spelled out.

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?

Although annotations already declare readOnly, openWorld, idempotent, and non-destructive, the description adds meaningful behavior: free/no-token access, default search over ~1000 recent filings, includeOlder triggering more requests, and specific error codes. This goes well beyond the structured safety hints and helps set expectations for cost and scope.

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 organized into scannable sections (behavior, returns, exclusions, cost, example). However, the detailed RETURNS block and a duplicate 'not for financial values' aside are somewhat redundant given an output schema already exists, adding length without new decision-relevant 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 tool with 7 parameters, annotations covering safety, and an output schema, the description still supplies everything needed: purpose, when/when-not-to-use, cost, error conditions, default scope behavior, and an example. 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 100%, so the baseline is 3; the schema already documents each parameter, including formats and ranges. The description adds value through a concrete example and by clarifying that includeOlder=true expands to the full historical archive at the cost of more requests, which enriches the meaning of that parameter beyond its 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?

The description opens with a specific verb+resource ('List a single company's SEC EDGAR filings') and immediately specifies the returned fields, filtering, and paging. It explicitly distinguishes itself from siblings like edgar_get_filing_document and edgar_get_company_facts, so an agent can identify when this tool applies 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?

It gives concrete use cases ('which filings exist', retrieving accession_number/document_url) and a dedicated WHEN NOT TO USE block naming alternatives for document text, XBRL numbers, and multi-company exports. The condition selecting each sibling is explicit, leaving no routing ambiguity.

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

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

Beyond the readOnly/idempotent/openWorld annotations, it discloses transport (HTTP GET to sec.gov), no token/no cost, a 6-hour cache, and the critical coverage limitation (only SEC registrants with a listed ticker – no delisted/private filers). It also explains match precedence and the COMPANY_NOT_FOUND error row.

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 organized under RETURNS / WHEN NOT TO USE / COST / EXAMPLE, so an agent can scan it fast. Minor redundancy: 'no API token, no cost' is repeated in the Behavior line and the COST line, costing a little tightness.

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 two-parameter read tool with an output schema, the description covers purpose, routing, cost, caching, coverage limits, match precedence, error code, and a worked example. 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 coverage is 100%, so the baseline is 3, but the description adds genuine semantic value: accepted query forms (ticker/CIK/name fragment), the meaning of maxMatchesPerQuery for name-fragment searches, and the rule that exact ticker/CIK matches beat name substring matches. A concrete example call reinforces this.

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: resolve US company tickers, CIKs or name fragments to official SEC CIK numbers/tickers/registrant names, naming the underlying source (company_tickers.json). It is clearly distinguishable from the filing- and facts-oriented siblings.

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

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

Explicitly says to use it first when only an identifier is needed, names the next-step tools (edgar_list_filings, edgar_get_company_facts), and adds a WHEN NOT TO USE clause noting other tools accept tickers/names directly. When/when-not/alternatives are all covered.

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