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

Annotations already mark this read-only/open-world, but the description goes well past them: per-company price ($0.003), the nuance that below-threshold companies are filtered out unbilled, that companies with no public board come back free with a status, per-call spend cap via run_max_charge_usd, and typical 5-15s vs multi-minute runtimes with a timeout remediation path. The subtle billing warning that raising maxCompanies higher than run_max_items can bill more than is returned is exactly the kind of hazard an agent cannot get from structured fields.

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, usage, exclusions, parameters, and operations are front-loaded in a logical order with no filler sentences. The one cost is the 21-field return enumeration, which is long but defensible given there is no output schema; a compact grouped phrasing would read better.

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-parameter, open-world, paid actor tool with no output schema, the definition covers what an agent needs before calling: cost model, caps, latency, timeout behavior, input ambiguity, non-obvious parameter interactions, and the return shape. Nothing material 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%, yet the description still adds decision-relevant meaning: links are exact while bare names "can match the wrong board," checkWebsite trades accuracy for speed, minOpenJobs filters unbilled, and — most importantly — titleKeywords only count matches and do not filter results. It also explains that run_max_items fills maxCompanies when unset, which materially changes cost interpretation beyond the schema text.

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

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

Opens with a specific verb+resource ("Measure hiring intent per company from its public job board") and enumerates the concrete outputs (open jobs, new jobs 7/30d, leadership openings, 0-100 score, hot/warm/cold signal). It explicitly distinguishes itself from the two closest siblings, company_website_enricher (tech stack/contacts) and company_team_finder (current staff), framing itself as a forward-looking buying/growth signal instead.

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?

States exactly when to reach for it ("sales triggers, recruiting leads or competitor hiring watch for a known list of companies") and exactly when not to ("Do not use to discover companies from scratch" or "for individual job search"), naming local_business_leads and federal_contract_finder as the discovery alternatives. Nothing about tool selection is left to inference.

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

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

Annotations only declare readOnly/openWorld/non-destructive/non-idempotent; the description goes well beyond them by disclosing billing mechanics ($0.002 per person, per person not per company), the hard spend cap via run_max_charge_usd and its default, the fact that companies with no readable team page are free, typical 5-15 s latency versus multi-minute crawls, and the 300 s timeout ceiling. It also flags that emailGuess is inferred rather than verified and carries emailConfidence, which is exactly the kind of caveat annotations cannot express.

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

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

Structure is strong and front-loaded: purpose, then sibling differentiation, then use/do-not-use, then parameter economics, then return fields, then runtime behavior. It is on the long side and the middle parameter paragraph is a dense run-on that merges cost, URL, and email-inference topics, costing it the top score, but nearly every clause carries actionable 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 10 optional parameters, no output schema, and a paid third-party Actor behind it, the description covers everything an agent needs: what each cost control does, what a run returns, timeout and cap behavior, and how to size inputs after a failure. The explicit return-field list compensates for the absent output schema.

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 100% (so 3 would be the baseline), the description adds semantics the schema does not: it identifies maxPeoplePerCompany and decisionMakersOnly as the real cost levers, explicitly explains that run_max_items limits returned items but not Actor billing, and explains that maxPagesPerCompany trades coverage for speed. It also clarifies that decisionMakersOnly results are not charged, which changes how an agent should configure the call.

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 and resource ('Find the named people at a company from its own public website') and enumerates exactly what is returned (name, title, seniority, department, decision-maker flag, email, LinkedIn, email pattern). It then explicitly disambiguates from two named alternatives by their unit of return ('one firmographic row per company' vs 'one row per person' vs 'academics ranked by publications').

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 spelled out on both sides: 'Use when you need decision makers or staff contacts at known companies' followed by three explicit exclusions routing to researcher_expert_finder, company_website_enricher, and the 'no team page' case. It also gives an operational preference ('Pasting the exact team page URL is faster and more reliable than a bare domain'), which is guidance an agent can act on immediately.

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 read-only and open-world, but the description adds pricing ($0.003/domain, unreachable sites and empty runs free), the spending cap mechanism, expected latency (5-15s typical, minutes for crawls), timeout escalation guidance, and the no-guessed-emails policy. These are material operational traits an agent cannot infer from annotations.

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

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

Dense and front-loaded: purpose, sibling differentiation, usage, then parameters, then behavior/pricing. The enumerated return-field list is long but earns its place given there is no output schema. A few clauses (e.g. the actor URL restated alongside the name) could be trimmed without loss.

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 nine parameters, no output schema, and an open-world crawl, the description covers inputs, return shape, cost model, latency, and failure modes. Nearly nothing an agent needs to call this correctly and predict its bill 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 per-parameter documentation is already handled. The description still adds cross-parameter meaning the schema does not: filters are applied before billing so filtered-out domains are free, and run_max_items also caps billing while raising maxDomains can bill more than is returned. That billing interaction is genuine value-add beyond the fields themselves.

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 ('Enrich company domains'), names the exact data sources (own site with robots.txt respected, DNS, RDAP), and enumerates the output categories. It explicitly distinguishes itself from company_team_finder and company_hiring_signals by saying it returns 'one firmographic row per company'.

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 the positive trigger ('when you have domains and need contact points, technographics or a filter like sites running Shopify or HubSpot') and two explicit exclusions routing to company_team_finder for people and email_domain_security_checker for email security. That is as close to a routing table as a description gets.

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 cover the read-only/open-world safety profile, and the description goes well beyond them: it names the underlying Apify Actor and account, the per-business price, that zero-result runs are not charged, and that run_max_charge_usd hard-caps spend. It also discloses non-obvious behaviors such as maxResults set above run_max_items billing more than is returned, and typical latency of 5-15 s with timeout handling.

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 alternatives, then parameter tips, then runtime/billing behavior — a sensible order for an agent that may stop reading early. It is dense but the 'Parameters:' block partly re-explains fields already documented in the schema, which is the only real redundancy.

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

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

With 13 parameters, no output schema and no required fields, the description carries the full burden and does so: it enumerates the per-item return fields (agentSummary, osmUrl, attribution, etc.), the envelope shape {actor, count, items}, and the ODbL attribution obligation. An agent has everything needed to call it and interpret the result without further discovery.

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 cross-parameter semantics the schema does not: radiusKm turns a boundary search into a circle, latitude+longitude pair with a 5 km default radius, and requireEmail sharply cuts results because few OSM entries list email. The maxResults vs. run_max_items billing interaction is the kind of meaning a schema cannot express, though a few tips merely restate schema text.

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

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

States a specific verb and resource ('List local businesses by category and place') with the data source (OpenStreetMap) and the fields returned. It explicitly names the two closest siblings, npi_provider_lists and trucking_company_leads, and explains how it differs from each (any business type worldwide vs. official healthcare/FMCSA registries).

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 concrete when-to-use example ('plumbers in Phoenix or cafes in a ZIP') and explicit when-not-to-use rules with the alternative named in each case: US healthcare goes to npi_provider_lists and reviews/ratings are out of scope entirely. It also flags the practical trap that whole states or countries are slow and tells the agent to narrow the area or raise run_timeout_secs.

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 declare read-only/open-world/non-destructive, and the description adds substantial operational context: it runs a paid Apify Actor on the user's account, charges $0.0015 per provider, has per-call spending caps, timeout behavior, and billing caveats around maxResults. It also describes the return shape and trimming behavior. No contradiction with annotations.

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

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

The first sentences front-load purpose and sibling differentiation, then parameter notes, then operational behavior. It is long but justified by 14 parameters; however some parameter details repeat the schema and could be trimmed. Minor redundancy 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?

For a complex 14-parameter tool with no output schema, the description explains the return envelope ({actor, count, items}), item fields, cost model, timeout handling, and result caps. An agent has enough information to call it correctly and interpret the response.

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 already documents all 14 parameters. The description adds some cross-parameter behavior (e.g., maxResults shared across specialty×area combinations) and clarifies territory narrowing, but much of the parameter prose duplicates schema descriptions. Baseline 3 is appropriate.

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 (build de-duplicated lists) and resource (US healthcare providers from the CMS NPI Registry), and explicitly distinguishes itself from local_business_leads and clinical_trial_leads. An agent can identify the tool's scope without opening the schema.

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

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

Provides explicit when-to-use cases (doctors, dentists, therapists, pharmacies or clinics in states/cities/ZIPs) and when-not-to-use cases (non-US providers, email addresses), plus names company_website_enricher as the follow-up for emails. This is complete routing guidance.

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

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

Annotations only cover safety (readOnly, non-destructive, open-world), while the description adds substantial context they do not: it runs Apify Actor pandadad0214/podcast-leads-finder on the caller's own account, costs $0.004 per podcast found, filters like onlyWithEmail/guestFriendlyOnly apply before billing, and emails come only from RSS feeds and are never guessed. It also discloses runtime (5-15s typical, 300s timeout cap) and the {actor, count, items} return envelope.

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?

It is front-loaded with purpose, then differentiation, then parameters, then runtime/billing, then return fields in a logical order, and nearly every sentence carries decision-relevant information. It is dense rather than lean, with mild redundancy between the behavior paragraph and the per-parameter notes on run_max_items, run_max_charge_usd, and maxResults.

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 13-parameter, no-output-schema tool with pay-per-result billing, the description covers the essentials an agent needs: what is returned per item, how filters affect billing, spend and item caps, timeout recovery guidance, and the response envelope. Nothing material is left to inference for correct invocation.

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

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

With 100% schema coverage the baseline is 3, and the description earns above that by explaining cross-parameter behavior the schema does not: keywords are searched separately and de-duplicated, deepSearch trades latency for up to 3x more shows, activeWithinDays=0 includes dormant shows, and run_max_items fills maxResults and limits what is billed. Some of this repeats schema text (e.g., maxResults' cost note), which keeps it below a 5.

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

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

"Find active podcasts to pitch by topic" gives a specific verb and resource, and it enumerates the returned fields (host, email, website, socials, episode count, guest-friendly signal). It explicitly contrasts itself with local_business_leads and company_team_finder, so an agent can distinguish it from siblings without opening schemas.

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

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

"Use when you need a podcast guesting, PR or sponsorship list for a niche" states the target case, and the description adds two exclusions with a named alternative: no audience/download numbers, and "for general topic popularity (use topic_trends_tracker)." Both when-to-use and when-not-to-use 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 annotations, the description discloses that the tool runs the Apify Actor pandadad0214/topic-trends-tracker on the caller's own Apify account, costs $0.002 per topic tracked, does not charge per result for empty finds, and has spending caps via run_max_charge_usd. It also describes typical runtime, timeout behavior, and the shape of returned JSON including structuredContent. This adds substantial operational context that the annotations do not provide.

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 long but appropriately front-loaded: it starts with what the tool does, then differentiates from alternatives, states exclusions, and explains parameters and behavior. The return-field list is dense but justified because there is no output schema. Some repetition between the description and schema prevents a perfect conciseness score, but the structure is clear and every major section serves a purpose.

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

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

Given the tool's complexity, ten parameters, lack of output schema, and actor-based execution model, the description is complete enough for an agent to call it correctly. It covers purpose, exclusions, alternatives, parameter interactions, cost controls, timeout behavior, and returned fields. No important operational or selection information 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 coverage is 100%, so the schema already documents all ten parameters well. The description still adds useful cross-parameter meaning, especially that run_max_items limits both returned items and billing while interacting with maxTopics, and that includeDailySeries materially increases output size. It also reinforces how topics resolve to Wikipedia articles and how URLs pin ambiguous names, though many individual parameter details remain primarily in 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 states a specific verb and resource: compare public interest in topics, brands, products, or people over time using real Wikipedia pageview counts. It lists concrete outputs such as daily/monthly views, change metrics, peaks, spikes, trend labels, and an interest index, which distinguishes it from sibling lead-generation tools. It also explicitly positions itself against Google Trends and names attention-measurement alternatives, so an agent can identify the tool without opening the schema.

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

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

The description gives explicit positive use cases: sizing or comparing interest, spotting spikes, and validating a topic. It also gives clear exclusions: not for search-keyword volume, not for social mentions, and not for topics without a Wikipedia article, which are returned as notFound. It names alternative tools such as podcast_leads_finder and company_hiring_signals to clarify when another tool is more appropriate.

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

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

Goes well beyond the readOnly/openWorld annotations: per-carrier pricing, free runs when nothing matches, a hard spend cap via run_max_charge_usd, the run_max_items/maxResults billing interaction, typical 5-15s runtimes with timeout remediation, and a candid caveat that phone/email are self-filed and may be personal or stale. Minor deduction because the timeout/charge semantics are restated rather than resolved in one place (it is unclear whether run_timeout_secs truncates results or errors).

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: purpose, differentiation, exclusions, then a parameter-behavior paragraph and a field list, with no filler. Some sentences duplicate schema text (run_max_charge_usd, run_timeout_secs defaults) and the 25-field return list is dense, but for a 24-parameter tool the density is earned.

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 supplies the full item shape (agentSummary, dotNumber, officers, safetyRating, fleetBand, etc.) plus the wrapper {actor, count, items}. It covers cost, latency, error remediation, and data-quality caveats, so nothing material to invoking 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 coverage is already 100%, so the baseline is 3; the description earns above that by explaining cross-parameter coupling the schema cannot express - mode=new consumes daysBack and sorts newest first, mode=search ignores daysBack and applies activeOnly, mode=lookup uses only dotNumbers. It also ranks the highest-signal narrowers (powerUnits/drivers bounds, carrierClass=forHire, requireEmail/requirePhone) and flags the run_max_items vs maxResults billing trap.

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 ('Pull US and Canadian motor carrier, broker and freight-forwarder records from official FMCSA data') and enumerates the returned fields. It explicitly distinguishes itself from two named siblings, local_business_leads and npi_provider_lists, so an agent can route correctly without opening a schema.

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

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

Provides concrete use cases (new-entrant carrier leads for insurance/factoring/ELD/dispatch, carriers by lane/state/fleet/cargo, DOT enrichment) and an explicit exclusion ('Do not use for shipment tracking, load boards or rates'). It also states which mode corresponds to which intent.

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