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

Adds substantial behavioral context beyond annotations: requires an APIFY_TOKEN, consumes Apify credits per call, reads public data and writes nothing, and each extra source adds a sub-actor run to the bill. There is mild tension with readOnlyHint=false (the call does trigger billable external runs), but the description is transparent about those side effects rather than hiding them.

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

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

Front-loaded with the core purpose, then supporting detail on defaults, return shape, and cost/auth. Efficient overall, though the second sentence is dense and packs defaults, costs, and return format into one long clause.

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 compensates by naming the return contents (composite score, recommended action, optional summary as a flat Clay-ready JSON row). Combined with its auth/cost disclosure, an agent has enough to invoke it correctly, though pagination/error behavior is 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?

Schema description coverage is 100%, so every parameter is already documented in the schema, including defaults, the billing effect of extra sources, and max_charge_usd semantics. The description largely restates this (defaults to hiring/tech-stack, sources add cost and dimensions), so it adds little beyond the schema — baseline 3.

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 ('Aggregate a company's GTM signals into one composite score') and clarifies it combines hiring + tech-stack (plus optionally funding/events/workplace) 'in one call'. This distinguishes it from single-signal siblings like scan_gtm_hiring_signals and detect_gtm_tech_stack without opening either schema.

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

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

Explains the aggregation context clearly: hiring and tech-stack run by default, others only when named in sources, all in a single call. This implies when to prefer the aggregator over individual scanners, but it never explicitly says 'use this instead of calling the single-signal tools separately' or names any when-not condition.

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 ends with 'Read only,' but the annotations declare readOnlyHint=false (a tool with side effects). This is a direct contradiction about the tool's safety profile, which is exactly the signal an agent relies on. Although the description otherwise discloses a lot (12 requests, 2-4s, no model, token and credit requirements, 7-day cache), the explicit read-only claim contradicts structured data and is capped at 1 per the rules.

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 result, and nearly every clause adds value (determinism, timing, billing, cache). It is dense and somewhat run-on, but not padded.

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

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

Despite having no output schema, the description fully characterizes the return (42 flat fields across five named families), resource costs, timing, determinism, caching and auth requirements. An agent has everything needed to call and interpret 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 description coverage is 100%, so every parameter (checks, domain, skipCache, max_charge_usd, check_endpoints, check_structured_data) is already documented in the schema. The description adds context about the output families but no extra parameter syntax or semantics, so the baseline of 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 action (given a domain, return whether an AI agent can read the site and what the policy says) and enumerates the five output families. This is unmistakably distinct from the GTM/sales-intelligence siblings, so an agent can route to it without ambiguity.

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 clear contexts and personas: a technical SEO/growth engineer preparing a site for AI crawlers, or an agency needing a before/after audit across a client list. There is no explicit when-not guidance, but no sibling competes for the same task, so this is adequate.

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

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

Annotations supply openWorldHint=true, idempotentHint=true, destructiveHint=false and readOnlyHint=false, but the description adds far more: no LinkedIn request/cookie/account, permalink-based attribution guarantee, index coverage latency ('days or weeks', 'many never appear'), removed fields with a date, row_type post/notice semantics, stable post_id, per-row degraded/degradation_reason, APIFY_TOKEN requirement and credit consumption. The closing 'Read only.' sits in mild tension with readOnlyHint=false, but the description itself discloses the credit side effect, so the two are complementary rather than contradictory.

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

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

Front-loaded with what the tool does, then caveats, then output shape. It is dense but nearly every sentence carries distinct, decision-relevant information (coverage limits, attribution rule, removed fields). Slightly long, but not padded.

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 full burden of describing returns — and it does: flat rows with permalink, author, excerpt, decoded publish date, row_type, post_id and degradation fields. Auth, cost, and coverage constraints are all covered, leaving nothing an agent needs to invoke it correctly.

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

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

Schema description coverage is 100% and the four parameters (company_urls, profile_urls, posted_since, max_charge_usd) are already richly documented in the schema, including the pre-charge skip semantics of posted_since. The description adds no parameter-level detail beyond what the schema states, so the baseline of 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 ('Point it at LinkedIn person profiles or company pages and it returns the posts a search engine has indexed'), plus the exact row shape returned. It also distinguishes itself from generic LinkedIn tools by specifying the mechanism (search-index based, no LinkedIn request), so an agent can tell what it is without opening the schema.

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

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

Gives clear usage context ('Point it at LinkedIn person profiles or company pages') and practical guidance ('filter on row_type before loading a table'). However, it never names an alternative sibling (e.g., map_company_social_presence, track_publication_cadence) or states when NOT to use it, so routing 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?

The description closes with 'Read only,' but the annotations declare readOnlyHint=false. That is a direct textual conflict about the tool's side-effect profile, which is the exact case the rubric scores 1. The otherwise rich behavioral detail (credits, 9 requests/contact, LLM key handling, null fallback) cannot offset a contradiction on the safety-relevant hint.

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 core contract is front-loaded in the first sentence and the remaining detail is organized roughly by concern (determinism, then optional verification, then fallback, then auth/cost). It runs long at ~10 sentences for a 9-param tool and repeats some material already covered by the schema, which keeps it from 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?

With no output schema, the description compensates by naming every returned field (department, seniority level, seniority_rank, classification_rule). It also covers auth (APIFY_TOKEN, LLM_API_KEY secret), cost model, and the no-key edge case, leaving nothing an agent needs in order to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including the conditional nature of full_name/company_domain and the defaults. The description largely restates this (required job_title, name/domain only read under verify_position) rather than adding syntax or semantics the schema lacks. Baseline 3 applies when the schema does the heavy lifting.

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

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

The opening states a specific verb+resource and its exact contract: 'One contact in, one classified row out. Give it a job title and it returns the department, the seniority level, a seniority_rank from 1 to 12... and classification_rule.' It also draws a boundary that no sibling provides ('This actor does not discover people: the name and title come from you'), so an agent can distinguish it from scan_gtm_hiring_signals or resolve_company_identity 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?

It gives clear context for use: only job_title is required, and it explains the conditional triggers for optional work (verify_position adds ~3s/9 requests and needs name+domain; use_llm_fallback only fires for titles the rules cannot place). It lacks explicit when-to-use-vs-sibling routing, but the 'does not discover people' statement effectively scopes it against the enrichment siblings.

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 past the annotations by disclosing auth requirements (APIFY_TOKEN), cost behavior (consumes Apify credits per domain), the 7-day cache, and the blocked=true low-confidence path instead of a false negative. It also states it reads public data and writes nothing to the target domain, which is nuanced against readOnlyHint=false (the run itself spends credits) but not a direct misrepresentation.

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

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

Purpose and the maturity taxonomy are front-loaded, then it layers output contents, an edge case, and operational constraints. It is a dense single block that is longer than strictly needed, but nearly 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?

With no output schema, the description correctly carries the return-shape burden by naming the fields an agent receives (tier, vendors, llms.txt status, robots.txt policy, evidence, blocked). Combined with the auth and cost notes, nothing an agent needs to call this 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 every parameter already carries its own documentation, making the baseline 3. The description reinforces the key semantics (vendors filter costs nothing extra, check_pricing caps the tier at 'deployed', batch mode precedence) but adds little that the schema doesn't already state.

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

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

Opens with a specific verb+resource (analyze a company domain for AI adoption) and enumerates the exact output taxonomy: an ai_maturity tier of none/declared/deployed/commercialized. That level of specificity lets an agent separate it from the neighboring detect_gtm_tech_stack, which covers general GTM stack rather than AI adoption depth.

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 context is implied rather than stated: batch mode 'takes precedence over domain', skipCache forces a fresh run, and check_pricing=false is only worth setting when 'deployed' is an acceptable ceiling. There is no explicit when-to-use/when-not or a named alternative among the many sibling detection 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 adds real value beyond the annotations: it discloses the APIFY_TOKEN requirement, that Apify credits are consumed per call, that only public data is read, and the shape of what comes back. The annotations already cover openWorld/idempotent/destructive, so the bar is lower and auth/cost disclosure is exactly the kind of extra context that earns credit. The only soft spot is that 'writes nothing' sits slightly awkwardly next to readOnlyHint=false (defensible, since the call spends credits), which keeps it from 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 purpose, then return shape, then behavioral constraints. Each sentence carries distinct information (what, what-you-get, cost/auth) with no filler or repetition of the schema.

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

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

With no output schema, the description usefully carries the return-value burden by describing a flat per-tool boolean JSON row. Combined with the schema's coverage of caching, filtering and spend caps, only minor items (error/async behavior, latency) are unaddressed, so this is close to complete for a detection 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 100%: all seven parameters, including the deprecated url/company_domain aliases, the 7-day cache behavior, the technologies filter and max_charge_usd, are already documented in the schema. The description adds no parameter-level detail beyond what is there, so the baseline of 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 ('Detect which GTM tools a company uses from its public website') and narrows the resource to CRM, sequencer and marketing automation signals, which separates it in substance from siblings like detect_ai_tooling or fingerprint_outbound_infrastructure. It does not name or contrast any sibling explicitly, so it falls just short of a 5.

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 implied by the stated source ('from its public website') and the 'Clay-ready JSON row' output, which signals an enrichment-pipeline context. However, there is no explicit when-to-use/when-not guidance, no prerequisites beyond the token, and no alternative tool is named despite many overlapping sibling enrichment 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?

Adds substantial behavior beyond the annotations: auth requirement (APIFY_TOKEN), per-call credit consumption, a 7-day result cache with a skipCache escape, a source_signals provenance array, and a data_completeness score. Minor tension with readOnlyHint=false given the claim 'writes nothing' — defensible since the call still consumes credits and creates a cached run, but the description could reconcile that explicitly.

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 dense sentences, front-loaded with the operation and output before the operational caveats. Efficient, though the first sentence is a long run-on that could be split for faster scanning.

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

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

With no output schema, the description carries the return-shape burden and does so (flat Clay-ready JSON row, source_signals, data_completeness). Combined with auth, cost, caching, and non-destructiveness notes, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so all six parameters (domain/domains precedence, batchSize caps, skipCache, max_charge_usd) are already documented in the schema. The description adds the return-row shape but no extra parameter semantics, so the 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 (enrich) and resource (company domain into firmographics) and enumerates the exact output fields (employee band, industry, HQ, founded year, revenue, logo, description). This is unmistakably distinct from siblings like detect_gtm_tech_stack or resolve_linkedin_url, so an agent can select 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?

The description supplies operating context (public data only, requires APIFY_TOKEN, consumes Apify credits, 7-day cache) but never states when to reach for this tool versus alternatives such as resolve_company_identity or score_icp_fit. Usage is implied by the resource name rather than explicitly routed.

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?

Despite readOnlyHint=false, the description discloses unusually rich behavior beyond the annotations: it requires an APIFY_TOKEN, consumes Apify credits per domain, uses public DNS/HTTP redirects only, and explicitly warns that sending-platform recall is partial by design (OAuth-connected sequencers leave no DNS trace), so an empty list means little. That is exactly the kind of caveat an agent needs.

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

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

The purpose and verdict semantics are front-loaded, and the dense enumeration of returned fields earns its place because there is no output schema. It is a long single block of prose, which costs some readability, but there is little genuinely redundant content.

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 full burden of explaining returns and does so thoroughly: the runs_outbound verdict values and their meanings, inbox providers, sending platforms, registration clusters, vendors, and SPF/DKIM/DMARC posture, plus auth and cost requirements. Nothing an agent needs to call this 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% with 10 well-documented parameters, so the schema does the heavy lifting and the baseline is 3. The description adds no syntax or defaulting guidance for individual parameters (it never mentions domain vs domains precedence, skipCache, or timeouts), so it does not exceed 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 description opens with a specific verb+resource+scope: 'Given a company domain, determine whether that company runs cold email outbound and on what stack.' That is far more precise than the sibling detect_gtm_tech_stack or detect_ai_tooling, and an agent can tell instantly what this tool is for.

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 context is implied clearly (domain-based cold-outbound fingerprinting), but there is no explicit when-to-use/when-not guidance and no comparison to adjacent siblings such as detect_gtm_tech_stack, which an agent might reasonably confuse with 'on what stack' detection.

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

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

Annotations only give the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false); the description adds substantive context beyond that: it reads public data, requires an APIFY_TOKEN, consumes Apify credits per call, bills per sub actor run, and stores a baseline snapshot. The phrase 'writes nothing' sits in mild tension with readOnlyHint=false, though that is most plausibly about external data rather than the billing/state side effects it does disclose.

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?

Four sentences, front-loaded with purpose and return shape, then parameter/cost guidance, then auth and billing constraints. Nothing is redundant, though the final sentence packs three separate constraints together rather densely.

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 tool with a nested object and no output schema, the description covers purpose, cost model, auth requirement, and baseline behavior. The return value is only sketched ('typed change events in flat, Clay-ready JSON'), which is thin given no output schema exists, but it is enough for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: omitting 'sources' costs five sub actor runs versus one, and 'previous_snapshot' replaces stored state and makes scheduled runs cheap. These are real decision-relevant semantics layered on top of the field descriptions.

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

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

The description states a specific verb and resource ('Monitor a company domain for changes') and enumerates the five monitored dimensions, plus what is returned ('only what changed as typed change events'). It is clear what the tool does, but it never distinguishes itself from the sibling scan/detect tools (scan_gtm_hiring_signals, detect_gtm_tech_stack, get_funding_press_signals) that cover the same domains, leaving the delta framing as the only implicit differentiator.

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?

'Since the last run' and the snapshot baseline imply a recurring/scheduled monitoring use case, and the description advises passing 'sources' and 'min_severity' to reduce scope and cost. However, it never states when to prefer this aggregator over the individual sibling signal tools, so the when-to-use guidance remains implied rather than explicit.

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

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

Adds real context beyond the annotations: it requires an APIFY_TOKEN and consumes Apify credits per call, and it returns deduplicated, dated events in flat Clay-ready JSON. The 'writes nothing' claim sits in mild tension with readOnlyHint=false, though the disclosed per-call credit consumption plausibly accounts for the non-read-only flag.

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 tight sentences: purpose and sources first, then return format, then behavioral/auth/cost constraints. No filler, and the most decision-relevant information is front-loaded.

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 still characterizes the return value (deduplicated, dated, flat Clay-ready JSON), and it discloses the auth requirement and cost model. Nothing needed to invoke this correctly appears to be 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 all five parameters are already documented, including the signal_types narrowing behavior and the max_charge_usd cap. The description echoes the event types and output shape but adds no syntax or format detail the schema lacks, so the 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 (Scan) and resource (Google News and PR wires) plus the exact event classes retrieved (funding rounds, exec moves, product launches, acquisitions). This clearly separates it from siblings like scan_gtm_hiring_signals or detect_gtm_tech_stack, which cover different signal families.

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 implied by the named sources and event types, and 'at any company domain' signals broad applicability, but there is no explicit when-to-use statement, no when-not, and no routing to alternative or complementary tools such as aggregate_gtm_signals. The reader must infer the fit from the content.

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 discloses a lot the annotations do not: cache (21 days unless skipCache), credit consumption and APIFY_TOKEN requirement, per-query latency, a max_queries rationale, the domain-scoped search that prevents brand collisions, and the rule that out-of-range years are returned and flagged. Against that, the closing claim 'Read only.' conflicts with readOnlyHint=false in the annotations, so the safety framing an agent sees in prose disagrees with the structured safety field.

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 core contract - domain in, flat row of declared attendance out, domain-scoped search - is front-loaded in the first two sentences, and the caveats that follow (hit rate, empty-row semantics, year flagging, cost) are all decision-relevant. It is dense rather than bloated, though the 'not an events database / not an exhibitor list' and 'Read only' tail sentences are the weakest and most repetitive.

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 has to explain return shape, and it does: one flat row, a year per event where resolvable, separate field for the company's own conference, and named diagnostic fields (coverage, fetch_status, queries_failed) for interpreting an empty result. Combined with cost/cache/auth disclosure, an agent has everything needed to call and interpret this 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 100%, and most of the description's parameter content (years being a soft filter, include_own_events being reported separately, max_queries sweet spot, cache behavior) is already documented in the schema property descriptions, so it largely restates structured data. The description does add operational meaning by tying years and include_own_events to what actually appears in the returned row, but the baseline of 3 applies when the schema carries the load.

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+resource: given a company domain it returns the third-party conferences/trade shows that company publicly says it attends, as one flat row. It also draws sharp boundaries against nearby concepts ('not an events database and not an exhibitor list') and separates the company's own conference from the attendance list, so an agent can distinguish it from siblings such as monitor_public_awards or get_funding_press_signals.

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 strong context for when this is the right call: expected hit rate (roughly 2 companies in 10), an explicit instruction to read coverage, fetch_status and queries_failed to distinguish 'no published events' from 'search could not see', and a directive to filter on event year rather than trusting the input filter. It stops short of naming a sibling tool to use instead for event/exhibitor data, so it is clear context without 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?

Adds substantial context beyond the annotations: discovery pipeline (homepage links, web-search fallback, pattern guessing) with validation, per-platform reliability caveats (X is URL-only, Instagram/Facebook counts best-effort), auth requirement (APIFY_TOKEN), and credit consumption. One minor tension: it asserts 'writes nothing' while readOnlyHint=false is defensible because the run writes a 7-day cache (exposed via skipCache).

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-loads what it maps, then output format, then method, then reliability limits, then requirements and cost. Five dense sentences with no filler, each carrying 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?

There is no output schema, and the description compensates by specifying the return format (flat Clay-ready JSON with URLs and follower counts), the one-of identifier requirement, cost/auth prerequisites, and per-platform data-quality limits. Nothing needed 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 platforms, skipCache, both identifiers, max_charge_usd, and includeFollowerCounts. The description only reinforces the required-one-of rule and the follower-count cost tradeoff, adding little beyond structured data; 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 (map) and resource (company social presence) and enumerates the exact five platforms covered, plus the output shape (profile URLs and follower counts). An agent can distinguish it from siblings like map_company_event_presence or resolve_linkedin_url 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?

Gives a real invocation constraint ('Provide at least one of company_domain or company_name') and a cost-driven toggle (set includeFollowerCounts false for URLs only, which is cheaper). However, it never says when to choose this tool over alternatives such as resolve_company_identity or enrich_company_firmographics, so usage is implied rather than routed.

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,' but the annotations declare readOnlyHint=false, which asserts the tool is not read-only. That is a direct contradiction of the structured safety signal an agent relies on to decide whether a call is side-effect free. The otherwise useful behavioral detail (APIFY_TOKEN requirement, Apify credit consumption, ~two-day US data lag, sort order, hard row cap) cannot compensate for a contradictory safety claim.

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 output shape and register list are front-loaded, and the paragraph packs a lot of decision-relevant facts into roughly 150 words without filler. There is some redundancy, notably the US two-day lag stated here and again in the window_days schema description, and the long single paragraph makes the cost and access constraints easy to skim past.

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 enumerates the returned columns (award count, total value, largest award, awarding body, award date, deep link, resolved domain) and names all five registers, so an agent knows what comes back. It also covers cost and credential prerequisites, though it does not address pagination, run-log access, or what happens when a window yields nothing.

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, including the string-typed numerics for Clay compatibility, the enum values, and the max_charge_usd semantics. The description reinforces register coverage and the sorting rationale behind max_entities, but largely restates the schema ('max_entities is the hard cap on billed rows', the two-day lag on window_days), adding little beyond 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?

The opening clause gives a specific verb and resource (returns companies that won public work, given a register and time window) and immediately specifies the grain ('one flat row per winning company rather than one per award'). It also pre-empts confusion with adjacent tool categories by stating it is not a tender feed, which no sibling tool covers.

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 clear conditions for use (pick a register plus a time window) and an explicit when-not ('not a tender feed and will not tell you what is open to bid on'), plus a concrete operational caveat that a one-day window on US registers returns little or nothing. It stops short of naming an alternative tool or route for the tender-feed use case, so the exclusion is stated but not redirected.

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 past the annotations: it discloses the billing model (per lead the sequencer confirms it created; gated, duplicate, skipped, failed and dry-run leads are free), auth requirements (v2 key for Instantly, v1 for Smartlead, APIFY_TOKEN), credit consumption, and that deduplicate's read still requires a key even on a dry run. The annotations only give a coarse safety profile (not read-only, not destructive); the description supplies the operational detail that matters.

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 result shape, then caveats and billing; every sentence carries real information. It is long, but the caller has 11 parameters and a nested object, so the length is largely earned rather than padding.

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, so the description carries the return-value burden and does so completely, enumerating the summary fields (received, no-email drops, ICP drops, duplicates, eligible, created, skipped, failed) plus per-address vendor errors. Auth, billing, dry-run semantics and campaign preconditions are all covered.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already documents leads, api_key, dry_run, deduplicate and others thoroughly. The description adds value by explaining cross-parameter interactions the schema states only locally: batch sending, the dedupe-vs-dry-run-vs-api_key dependency, and what 'the rest' means after drops.

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 ('push enriched lead rows into an existing Instantly or Smartlead campaign') and enumerates the transformations it performs (field mapping, ICP gate, dedupe, batching). It is the only write/outbound tool among siblings that are otherwise read-and-enrich operations, and the description makes that distinction unmissable.

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 bounds when-not-to-use: 'The campaign must already exist; this does not create campaigns or write sequence copy.' It also routes the agent to a safe validation path ('Set dry_run true ... which is the safe way to check a mapping against a new campaign') and names an upstream sibling (score_icp_fit) as the source of dataset_id.

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: conflict detection instead of merging, LinkedIn URLs returned only when verified with the reason surfaced in linkedin_verification, live public-data reads with no data writes, an APIFY_TOKEN requirement, and per-call Apify credit consumption. The credit/actor-run side effect is exactly what reconciles the non-read-only annotation with the 'writes nothing' phrasing, so an agent is not misled.

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 sentence carries information (behavior, conflict policy, verification, alternative routing, auth, cost). It is one dense block rather than cleanly separated purpose/usage/behavior sections, which slightly hurts scanability for a description of this length.

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 covers the return shape (name, primary domain, LinkedIn URL, per-field 0-100 confidence, overall score, match method, linkedin_verification). It also covers auth, cost, input preconditions, and the sibling alternative, so 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 coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the three identity inputs are cross-checked against each other, unspecified ones are resolved, and disagreeing domain/LinkedIn inputs are flagged rather than merged. It also restates the at-least-one-input rule that the zero-required-parameter schema does not enforce via anyOf.

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 + outcome: resolve name/domain/LinkedIn URL into one canonical identity with per-field confidence scores, an overall score, and a match method. It explicitly differentiates itself from the sibling resolve_linkedin_url ('use resolve_linkedin_url instead when you only need the LinkedIn company URL'), so an agent can route without opening either schema.

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

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

Gives an explicit condition and alternative: 'Use this to reconcile or deduplicate records you already hold; use resolve_linkedin_url instead when you only need the LinkedIn company URL for a domain or name.' It also states the input precondition ('Provide at least one of company_name, domain, or linkedin_url'), leaving nothing 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 real behavioral context: ~6/10 resolve rate, defaults that reject non-identical names, requirement for APIFY_TOKEN, credit consumption, cache TTLs implied via skipCache. It does not restate readOnlyHint. However, the annotation readOnlyHint=false contradicts the description's closing 'Read only.'

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-loads what the tool does and its output, then explains the matching policy and the null-rate caveat. Slightly long, but every sentence carries non-obvious information. Could trim the sibling list of registers if it ever grew.

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

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

Despite 9 parameters and no output schema, the description gives an agent everything needed: what it returns, the match semantics, the failure mode, the cost/auth model, and the trustworthiness of nulls. No material gap remains.

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 schema carries parameter detail. The description still adds value by explaining why match_strictness defaults to exact and why fuzzy is risky, and by framing SEC requester fields as regulatory requirements rather than arbitrary inputs.

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 (resolve) and resource (legal entity) with a precise output contract: registered legal name, company number, jurisdiction, status, entity type, LEI, VAT. It also names the three data sources (Companies House, GLEIF, SEC EDGAR), which distinguishes it clearly from siblings like resolve_company_identity.

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

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

Explicitly states when to use fuzzy vs exact, when to use legal_name_hint, and what a null answer means. It also states when NOT to use it: 'not a company database and not a credit or risk product.' This is exactly the routing guidance an agent needs.

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?

Discloses far more than the annotations: the exact verification rule for returning a URL vs null, that no request is sent to LinkedIn, 7-day caching, that it requires an APIFY_TOKEN, and that it consumes Apify credits per call. This explains why readOnlyHint is false (credit side effects) despite the tool writing no data, which the description states explicitly.

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

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

Front-loaded with purpose and the sibling distinction, then verification, then inputs, then routing and cost. Dense and every clause carries information, though it is delivered as one long block rather than broken into scannable units.

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 still characterizes the return shape (flat Clay-ready JSON row with confidence_score, social links, optional firmographics, and null-plus-reason when unverified). For a 6-param, 0-required, externally-billed call, nothing an agent needs 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 value beyond the schema: the 'at least one of company_domain or company_name' constraint is not expressed by required=0, and it explains what minConfidenceScore buys (fewer, surer answers vs more wrong ones).

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 ('Resolve a company domain or name to its LinkedIn company URL') plus the returned payload (confidence_score, social links, firmographics). It explicitly names and distinguishes the sibling resolve_company_identity, so an agent can route correctly without opening either schema.

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

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

Gives a positive trigger ('Use this when the LinkedIn company URL is the answer you need'), names the alternative and its distinct purpose ('use resolve_company_identity instead to cross-check a name, domain, and LinkedIn URL you already hold'), and states the input precondition ('Provide at least one of company_domain or company_name').

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds genuinely useful context not in the annotations: it reads public data, writes nothing, requires an APIFY_TOKEN, and consumes Apify credits per call. It does not disclose rate limits or failure modes, but for a read-only scraper this is strong additional context.

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 what it does and what it returns, followed by the routing rule to the sibling, then the operational requirements. Every sentence earns its place with 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?

For an 8-param, no-output-schema, open-world scraper, the description covers purpose, return shape ("flat, Clay-ready JSON row"), routing, and operational prerequisites. Slightly less than complete because it doesn't mention the batch mode's limitation (that this single-call tool supplies no list) which the schema notes, but the schema already carries that.

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 all 8 parameters (including mode's enum semantics and velocity-mode dependencies on previous_gtm_role_count/previous_run_date) are already fully documented in the schema. The description adds no parameter-level detail beyond what the schema provides, which is correct given full coverage — baseline 3.

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 (scan) and resource (career pages) and defines the narrow scope (GTM hiring activity: sales, marketing, revops). It explicitly names the sibling it differs from, scan_job_board_keywords, and the axis of difference (GTM-only vs arbitrary keyword counts).

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 case ("for a go-to-market hiring verdict") and an explicit alternative with the condition that selects it ("use scan_job_board_keywords instead to count open roles in categories or keywords you choose, including non-GTM roles"). No inference required.

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 openWorld, idempotent and destructive hints, so the description's job is to add what they don't say — and it does: requires an APIFY_TOKEN, consumes Apify credits per call, and reads public data only. There is a mild tension between readOnlyHint=false and the phrase 'writes nothing', though the consumer of Apify credits plausibly explains the false hint; no strong contradiction.

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?

Four tightly packed sentences with the purpose front-loaded and no filler. The final sentence stacks four separate facts (public data, no writes, token requirement, credit cost) which makes it dense, but each clause 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?

With no output schema, the description tells the agent what comes back (matched role counts and titles per category as a flat, Clay-ready JSON row). Combined with full schema coverage on all seven parameters and the cost/auth disclosure, an agent has everything needed to call this 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 100%, so the baseline is 3, but the description adds real meaning: it clarifies that role_categories are user-chosen (engineering, finance, a product name in a job ad) and that custom_keywords work with the Custom category, giving the agent the intent behind two of the seven parameters.

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 (scan) and resource (a company's job board for roles in chosen categories), and names the exact surface it covers (Greenhouse, Lever, Ashby, Workday, Rippling) plus the return shape. It also names the sibling it is not (scan_gtm_hiring_signals), so an agent can distinguish the two 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?

Gives an explicit selection rule: use this one 'when you choose the role categories or keywords'; use scan_gtm_hiring_signals 'instead for the fixed sales and marketing hiring verdict.' That is a clean when/when-not with the alternative named.

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

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

Annotations cover the safety profile (destructiveHint=false, idempotentHint=true, openWorldHint=true), so the bar is lower, and the description still adds real behavioral context: it requires an APIFY_TOKEN and consumes Apify credits per call, which matters for an agent deciding to invoke it. It also declares 'reads public data and writes nothing', which sits in mild tension with readOnlyHint=false (the schema's fetch_signals spawns billable sub-actors), but this reads as credit/spend semantics rather than a genuine contradiction.

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?

Four sentences, all front-loaded: purpose and outputs first, then ICP configuration, then operational requirements. Every sentence carries information the agent needs and none repeats the title or name.

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 44 parameters, no output schema, and nested objects, the description does well to state the return shape inline and to disclose cost and auth requirements. It omits the degraded-row / fetch_signals behavior, but that is documented in the schema, so the omission is acceptable 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 and the schema already explains every one of the 44 parameters in detail. The description adds only the cross-parameter dependency that icp_description needs llm_api_key; it does not summarize the signal-override inputs or the thresholds. Adequate but not additive.

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 specific verb and resource ('Score a company against your ideal customer profile') and immediately enumerates the concrete outputs (0-100 icp_score, A-D icp_tier, per-signal breakdown). It is clearly distinguishable from sibling enrichment tools like enrich_company_firmographics or aggregate_gtm_signals, which gather signals rather than score them.

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 useful guidance on the three ways to define an ICP (template, scoring_config, icp_description) and notes that icp_description requires llm_api_key. However, it never states when to prefer this tool over the sibling signal-gathering tools, nor what prerequisites (e.g. already-enriched firmographics) are expected. Usage is implied rather than routed.

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?

With sparse annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true), the description carries the disclosure burden well: credit consumption, auth requirement, 3-day cache, sample-vs-census estimation, nulling instead of reporting unreliable dates, partial_result on timeout, and public-data-only sourcing. The 'writes nothing' claim sits slightly oddly against readOnlyHint=false, but false is a non-claim rather than an assertion of writes, so this is a clarifying detail rather than a contradiction.

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?

Roughly 250 words, but front-loaded with the purpose and trend definition before the caveats. Almost every sentence carries a distinct fact (date_source_reliable, counts_are_estimate, credit cost), though the density is high enough that a couple of clauses could be tightened.

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

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

There is no output schema, so the description must carry return values, and it does: the 30/90/12-month counts, monthly average, the cadence_trend enum values, the trend normalization window, format mix, byline count, and discovery method. Nothing an agent needs to call or interpret this tool 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 goes further: it explains the page-budget/sampling tradeoff behind max_pages_to_date (counts_are_estimate), the per-domain wall clock that yields partial_result, the cost cap semantics, and cache bypass. Several parameters gain operational meaning beyond their 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?

Opens with a specific verb and resource: 'measure how much long-form work that company publishes and whether the rate is rising or falling.' It explicitly bounds the scope ('EDITORIAL output volume, not product changelogs') and describes the exact outputs, so an agent can distinguish it from any sibling like capture_linkedin_posts_and_commenters without opening the schema.

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

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

Gives clear usage context: it rejects release feeds, requires an APIFY_TOKEN, consumes Apify credits per domain, reads only public sitemaps/feeds/pages, and instructs the agent to check date_source_reliable before quoting counts. It does not name a sibling alternative or state an explicit when-not-to-use condition, so it lands just short of a 5.

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