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

Annotations already declare readOnly/openWorld/idempotent, but the description adds far more: the Apify Actor backing the call, sec.gov throttling at <=5 req/s, the required APIFY_TOKEN environment variable, 5-60 s typical runtime with a ~5 minute wait ceiling, per-event pricing, and the fact that unresolvable companies yield error rows rather than failing the whole run. None of this is derivable from the annotations or schema.

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

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

Long but front-loaded and clearly segmented with WHEN TO USE / BEHAVIOR / COST / RETURNS / WHEN NOT TO USE / PARAMETERS / EXAMPLE headers. The 1-4 company rule is stated twice (WHEN TO USE and WHEN NOT TO USE), a minor redundancy in an otherwise dense, purposeful block.

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 paid, long-running, open-world batch tool this covers everything an agent needs: cost model with a worked example, auth requirement, timeout behavior, partial-failure semantics, and parameter-mode interactions. Although an output schema exists, the description still usefully explains the row taxonomy and error codes without over-relying on it.

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

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

Schema coverage is 100%, so the baseline is 3, and much of the parameter detail (defaults, [] semantics, case sensitivity) is repeated from the schema. The description does add value by tying parameters to mode applicability and, crucially, linking maxFilingsPerCompany / metrics / maxFactsPerMetric to the billing formula ('size those three numbers first'), which changes how an agent should choose values.

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 with scope (bulk export of SEC EDGAR filings, facts and text excerpts for up to 50 companies in one call) and enumerates the concrete data returned. It explicitly contrasts itself with the per-company siblings (edgar_list_filings / edgar_get_company_facts), so an agent can distinguish it from them without 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?

Provides an explicit WHEN TO USE threshold (5+ companies, or bulk excerpts), the alternative for 1-4 companies with a naming of the free tools, and a WHEN NOT TO USE section ruling out interactive lookups, real-time quotes, non-US companies, and investment advice. The mode semantics (filings/facts/both) further select the correct invocation.

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 readOnly/idempotent/openWorld, but the description adds behavior they cannot express: a <=5 req/s throttle, free/direct-sec.gov cost with no APIFY_TOKEN, retryable vs terminal error codes (COMPANY_NOT_FOUND, NOT_FOUND, SEC_FETCH_FAILED), restatement semantics behind dedupe, sort order, and pagination. This is unusually rich disclosure for a read tool.

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

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

Front-loaded with the two modes and then organized under Behavior/RETURNS/WHEN NOT TO USE/COST/PARAMETERS/EXAMPLE headings, so it is scannable despite its length. The PARAMETERS section partially restates schema text, which is mild redundancy, but the mode-interaction details justify the 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?

For a 10-parameter tool with two operating modes, the description covers mode selection, ignored-parameter interactions, filter semantics, dedupe, sorting/paging, error codes, cost, and a worked example. Even though an output schema exists, the inline RETURNS note about 'start is null for instant concepts' adds needed row-shape context.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description meaningfully exceeds the schema: it explains that concepts switches mode (and which params are ignored in each), that filters combine with AND, that concept names are case-sensitive and never-reported names surface in meta.missing_concepts rather than failing, and that revenue is often tagged RevenueFromContractWithCustomerExcludingAssessedTax.

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 precise verb+resource (get reported XBRL financial data for one company) and names the data source (SEC companyfacts API) with concrete example concepts. It explicitly distinguishes its two modes and contrasts itself with edgar_get_concept_across_companies, so an agent can tell it apart from every 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?

Provides an explicit WHEN NOT TO USE section routing to edgar_list_filings + edgar_get_filing_document for documents, and to edgar_get_concept_across_companies / edgar_batch_export for multi-company work. It also prescribes the workflow 'run list mode with search "revenue" first' before requesting values, which is actionable selection guidance.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description layers on operational detail they cannot express: throttling at <=5 req/s, one frame download per call, a 6-hour-cached ticker map, named error codes (NOT_FOUND non-retryable vs SEC_FETCH_FAILED retryable), and cost/credential implications (free, no APIFY_TOKEN).

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 structured into Behavior / Returns / When-not-to-use / Cost / Parameters / Example blocks, so scanning is easy. The PARAMETERS block is long and partially re-states schema-documented enum values and defaults, which is the only mild 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?

Complete for an 8-parameter tool: required vs optional params and their interactions, filtering/ranking/paging order of operations, an inline call example, return shape (ranked rows plus meta frame/source_url), and error taxonomy. An output schema exists, so not re-explaining every field is correct.

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

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

Although schema coverage is already 100%, the description adds genuinely new semantics: the period/concept type coupling (flow items need durations, balance-sheet items need instant 'I' frames, wrong kind returns NOT_FOUND), the case-sensitive concept/unit/taxonomy tuple that must exist together, unit conventions per concept class, and the fact that 'companies' filters post-download with silent skips and that rank is recomputed after filtering and sorting.

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 precise verb+resource+scope: 'get one XBRL concept ... for every SEC filer that reported it, using the SEC frames API.' It also names the exact mechanism (frames API) and the sibling it is NOT for (edgar_get_company_facts), so an agent can distinguish it from all five siblings 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?

Explicit when-to-use ('free multi-company screening and peer comparison') with concrete query examples, plus a dedicated 'WHEN NOT TO USE' line routing to edgar_get_company_facts for single-company time series and edgar_list_filings for filings. Both the positive and negative conditions are stated.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description goes well beyond them: the throttle ceiling (<=5 requests/s), the reason pagination is needed (10-Ks exceeding 500k characters), the full error enumeration with SEC_FETCH_FAILED flagged retryable, and the cost model (free, no APIFY_TOKEN). It also warns that raw and text modes use incompatible offset spaces.

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?

Long, but front-loaded and partitioned into labeled sections (Behavior, RETURNS, WHEN NOT TO USE, COST, PARAMETERS, EXAMPLE) so a reader can jump straight to what matters. A few lines restate schema content, which costs it the top score, but almost every sentence carries distinct 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 7-parameter, zero-required paging tool with mutually exclusive identification paths, the definition covers everything needed: both input modes, precedence, unit semantics, the loop termination condition, raw-mode divergence, error handling, and cost. With an output schema present, it correctly avoids over-explaining the response payload.

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 meaning: the precedence rule ('documentUrl wins if present; company/accessionNumber/document are then ignored'), the requirement that company and accessionNumber be supplied together or INVALID_INPUT results, the paging loop ('offset = nextOffset until hasMore is false'), and that .txt files bypass HTML conversion in either mode.

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 ('Fetch the text of an SEC filing document from the sec.gov EDGAR archives') plus the transformation applied (HTML to plain text) and the delivery shape (character-paged chunks). It explicitly contrasts itself with edgar_list_filings (discovery) and edgar_get_company_facts (structured values), so an agent can route correctly without 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?

Contains a dedicated WHEN NOT TO USE clause naming both relevant siblings and the condition that selects each ('to find which filings exist use edgar_list_filings first; for structured financial values use edgar_get_company_facts'). The two valid identification paths (documentUrl OR company + accessionNumber) are also stated as explicit alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds behavior beyond them: one GET to the -index.htm page, throttling to <=5 req/s shared across edgar_* tools, a possible cached ticker-map request during company resolution, row ordering, enumerated error codes with the retryable one flagged, and an explicit cost statement (no APIFY_TOKEN/billing).

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, then labeled blocks (Behavior, RETURNS, WHEN NOT TO USE, COST, PARAMETERS, EXAMPLE) so an agent can skim to the needed section. It is dense and longer than average, but almost every clause carries non-redundant information; only the example at the end is somewhat expendable.

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 six-parameter, zero-required tool with an output schema, this leaves nothing an agent needs unanswered: invocation modes, filter caveats, error taxonomy, throttling, and the exact example response shape (including meta.form and meta.period_of_report) are all 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 100%, yet the description adds real semantics beyond it: indexUrl wins over company+accessionNumber, both must be supplied together else INVALID_INPUT, company only locates the filing folder so any co-filer CIK works, docTypes matching is exact so 'EX-21' will not match 'EX-21.1', the filter is applied before paging and meta.document_count ignores it, and url is stripped of the inline-XBRL viewer prefix.

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 every file of ONE SEC filing from its EDGAR filing index page') and enumerates the row types (primary document, exhibits, XBRL data files) plus the header facts returned. It is immediately distinguishable from edgar_get_filing_document, which reads a single document's text, and from edgar_list_filings, which finds filings.

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 positive triggers ('when you need an exhibit or attachment rather than the primary document', with quoted examples) and an explicit WHEN NOT TO USE block routing to edgar_list_filings, edgar_get_filing_document and edgar_get_company_facts. The handoff ('pass a row's url to edgar_get_filing_document') closes the loop.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description goes well beyond: it discloses the upstream endpoint, a <=5 req/s throttle, the extra SEC request cost of includeOlder, filter-before-paging semantics, and named error codes with a retryable flag. This is exactly the behavioral context annotations cannot carry.

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 and organized into labeled sections (Behavior, RETURNS, WHEN NOT TO USE, COST, PARAMETERS, EXAMPLE) with the example last. It is on the long side and the sibling alternatives are effectively repeated (edgar_get_company_facts appears in both the purpose line and WHEN NOT TO USE), which is minor redundancy but not waste.

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

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

For a 7-parameter, paginated, free-of-charge list tool with an output schema, every gap is closed: resolution rules, filter semantics, paging continuation (offset = nextOffset), return shape, error handling, and cost/token requirements. Nothing an agent needs 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 already 100% (baseline 3), but the description adds real meaning: the company disambiguation rule (numeric = CIK, text = ticker then name fragment), the fact that formTypes is exact case-insensitive equality so 10-K excludes 10-K/A, that since/until bind filing_date not report_date, and how includeOlder changes cost. This clearly exceeds 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 (List) plus resource (SEC EDGAR filings for a single company), with scope details (newest first, what fields come back) and explicit negative framing that names the sibling tools it is not (edgar_get_company_facts, edgar_get_filing_document). An agent can distinguish it from every sibling on name alone.

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 'Use to find which filings exist' section, a dedicated 'WHEN NOT TO USE' block that routes document text to edgar_get_filing_document, XBRL numbers to edgar_get_company_facts, and multi-company queries to edgar_get_concept_across_companies / edgar_batch_export. Both the when and the when-not with named alternatives 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?

Beyond the readOnly/idempotent/openWorld annotations, it discloses the throttling rate (<=5 req/s), a 6-hour cache on the ticker map, coverage limits (listed-ticker SEC registrants only, no delisted/private filers), and per-query error-row isolation so batch failures don't cascade. This is exactly the extra context annotations cannot carry.

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 heavily sectioned (Behavior, RETURNS, WHEN NOT TO USE, COST, PARAMETERS, EXAMPLE), so it scans well. It is long, though, and the PARAMETERS and COST sections partly restate the schema and title, adding some 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?

Even though an output schema exists, the description sketches the return shape (company_match rows with 10-digit padded CIK and match rule, plus COMPANY_NOT_FOUND rows) and gives a worked example. Coverage limits, precedence, and failure behavior are all addressed, so nothing needed 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 already 100%, but the description adds non-obvious resolution semantics: all-digit strings try CIK first, then exact case-insensitive ticker (dash for class shares), then name substring, first match wins and later rules are skipped. It also explains when maxMatchesPerQuery actually matters (broad fragments, multi-ticker CIKs like GOOG/GOOGL).

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+source of truth: resolve tickers/CIKs/name fragments to official SEC CIK numbers using company_tickers.json. It distinguishes itself from siblings by naming edgar_list_filings and edgar_get_company_facts as the downstream tools for filings and financial data.

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 this first when only an identifier is needed or to confirm which company a name refers to, then routes to specific alternatives. A dedicated WHEN NOT TO USE section states it is not for filings or financial values and notes other tools accept tickers/names directly.

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