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

The description ends with 'Read only', but annotations declare readOnlyHint=false, a direct contradiction of the structured safety hint. Although the description otherwise discloses valuable behavior (Apify token requirement, per-row credit cost, limit default of 1000, reported truncation), the explicit read-only claim against a readOnlyHint=false annotation is a serious inconsistency that an agent would rely on incorrectly.

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 exclusions, then the at-least-one-filter rule, then the cost warning, then the token/auth note. Dense but each sentence carries a distinct operational fact; only the closing 'Read only' is wasted (and harmful) given the rest of the payload.

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 17-parameter filter tool with no output schema, the description supplies the missing return-value context ('44 fields per company, the same shape resolve_company returns'), the cost and truncation model, the auth requirement, and the identifier exclusion. Nothing an agent needs to call it correctly is absent.

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; however the description adds the limit default (1000) and the per-row billing model, neither of which appear in the schema text, and enumerates the filter families so the agent knows what dimension each parameter targets. It adds real meaning over the schema rather than repeating it.

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 (build a list of listed companies) and immediately scopes it against identifier-based lookup, explicitly naming siblings resolve_company, qualify_company and get_reporting_timing as the tools to use for specific companies. An agent can distinguish it from every sibling 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 (derive a universe from filters), when-not-to-use (you already hold identifiers, or want specific companies), and hard operational rules: at least one filter is required, and limit must be set explicitly. Also warns it does NOT accept company identifiers, which is the key selection trap against the sibling tools.

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

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

The description closes with 'Read only.' while the annotations declare readOnlyHint=false, a direct contradiction of the declared safety profile (flagged as Annotation Contradiction). Setting that aside, the description is otherwise rich — it discloses cost ('Charged per aggregate row returned'), auth ('Requires an APIFY_TOKEN and consumes Apify credits'), and the minimum-filter constraint — but the explicit contradiction with structured metadata forces the floor score.

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 shape before any parameter talk, then progressively adds window defaults, constraints, routing, cost and auth. Nine sentences with essentially no filler; each carries either a routing rule, a constraint, or a cost/auth disclosure.

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 carries the return-value burden and does so — aggregate rows per bucket with period start/end, event count, company count, estimated share and mean confidence. Combined with cost model, auth requirement, minimum-filter rule and sibling routing, an agent has everything needed to call this correctly for a 22-parameter 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 coverage is 100%, so the baseline is 3, but the description goes beyond it: it names the season-specific controls (season_group_by for week/month bucketing, season_split_by for a second dimension, season_from/season_to for the window), groups the population filters by family, and adds a constraint not encoded anywhere in the schema ('company identifiers are not accepted'). It stops short of explaining the semantics of individual filter enums, which the schema already covers.

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 ('Show how reporting load is distributed over time') and immediately names the sibling it is not for ('not to time one account; for a single company use get_reporting_timing'). An agent can distinguish it from get_reporting_timing and build_company_universe 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?

Explicit routing rule ('Use this to plan campaign timing across a market... for a single company use get_reporting_timing'), an explicit hard precondition ('At least one filter is required and company identifiers are not accepted'), and a pointer to the filter vocabulary build_company_universe uses. When-to-use, when-not-to-use, and the alternative are all 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?

The description is unusually rich about behavior beyond the annotations: dates are PREDICTED not announced, estimate/confidence thresholds at 0.80 and 0.50, per-row credit charging, APIFY_TOKEN requirement, and the non-US no-guess policy. However, it closes with 'Read only.' while the annotations declare readOnlyHint=false, a direct conflict on the read/write axis that an agent may rely on when deciding whether a call has side effects.

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?

One dense passage with no filler: purpose first, then the returned shape, then the prediction caveat, then the US-only and billing constraints last. It is long, but every sentence carries a fact an agent needs; the only cost is that the constraint/cost material is buried in a paragraph rather than surfaced separately.

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 30-parameter, no-required-parameter tool with no output schema, the description supplies the missing return-value semantics (field names, window_status vocabulary, estimate flags, confidence bands) and the commercial/geographic constraints an agent cannot infer from the schema. Nothing material for correct invocation is absent.

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, and the description earns above baseline by tying parameters to meaning the schema does not: window_lead_days/window_lag_days (70/42) define the window whose state window_status reports, min_cadence_confidence interacts with null timing blocks, and 'which is the field to filter on' tells the agent that window_statuses is the primary dial. It does not attempt to explain the other ~25 filter parameters, which the schema already covers.

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: it predicts when a public company next reports and defines an outreach window around that event, with a concrete list of returned dimensions (next reporting event, days to event, window open/close). It is clearly a timing tool and not an identity or qualification tool, but it never names or contrasts itself with the sibling get_reporting_season, which is the tool an agent is most likely to confuse it with.

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 a hard applicability boundary ('TIMING ROWS COVER US COMPANIES ONLY') and what happens outside it (a stated timing_unavailable_reason rather than a guess, still billed), plus which field to filter on (window_status) and that max_days_to_event is a cost control. What is missing is routing guidance against the sibling alternatives (get_reporting_season, resolve_company, qualify_company) for the same company 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?

The description says 'Read only' while annotations declare readOnlyHint=false, which directly contradicts the safety profile. Although it otherwise adds useful behavioral context such as APIFY_TOKEN, Apify credit consumption, and unmatched-company handling, the contradiction requires a score of 1.

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 then organized by modes, default behavior, usage, identifiers, filters, and cost/auth. It is dense but appropriate for a 26-parameter tool, with only minor extra phrasing that still earns its place as use-case context.

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

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

For a complex 26-parameter tool with no output schema, the description covers identifier inputs, filter families, cost, auth, and default return behavior including is_listed null. It does not detail the full return shape and contains the incorrect 'Read only' claim, leaving a small completeness 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 schema already documents all 26 parameters in detail. The description groups identifiers and optional filters but adds little syntax or meaning beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource: answer whether a company is publicly listed. Distinguishes itself from resolve_company by naming when to use the sibling instead. An agent can tell what this tool does 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?

Explicitly says to use this to split a prospect list into listed and private companies before outreach, and to use resolve_company when full identity fields are needed. It also explains the listed_only, suppress_listed, and assume_unmatched_is_private modes.

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

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

The description adds genuinely valuable behavior beyond the annotations: per-row billing including no_match rows, an exactly-one-row guarantee, no_match semantics, and the APIFY_TOKEN requirement. However, it closes with 'Read only' while the annotation declares readOnlyHint: false, so the safety claim an agent would rely on is contradicted by the structured field. That conflict prevents a higher score despite the otherwise rich disclosure.

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

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

Purpose is front-loaded in sentence one, followed by output shape, edge-case behavior, sibling routing, filter semantics, and pricing. Each sentence carries distinct information, but the block is long and could be tightened; nothing is filler, yet it is denser than it needs to be for a tool 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 23-parameter tool with no output schema and no required parameters, the description covers what an agent needs: input identifiers, the 44-field return shape, the no_match outcome, how to read provenance, filter behavior, auth requirements, and cost model. Nothing material is left for the agent 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 100% and the per-parameter descriptions are unusually strong, so the baseline is 3. The description still adds a real semantic not present in the schema: the filter inputs (exchange_codes, country_codes, regions, sectors, etc.) narrow which matched rows return rather than acting as selectors, and it explains how to interpret match_method/matched_on. That is meaningful added meaning over the schema.

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

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

The first sentence gives a precise verb (resolve) plus the exact set of accepted identifier types (domain, ticker, ISIN, LEI, CIK, name) and the resource (a listed company identity). It is immediately distinguishable from qualify_company (yes/no listed status) and build_company_universe (filter-driven). No ambiguity about what comes back.

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 the selecting condition ('when you hold identifiers and need the listed identity behind them') and then names three alternatives with their own conditions: qualify_company for a yes/no, get_reporting_timing for dates, build_company_universe for filters. This is textbook when-to-use/when-not-to-use routing.

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