HirePulse: Jobs, Ads, SEO, YouTube & AliExpress Data Tools

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the no-effect-on-terminal-states rule, which is exactly what makes the idempotent hint meaningful, plus the fact that updated run details come back. It omits auth/permission requirements and any rate-limit behavior.

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

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

Front-loaded with the core action and the state constraint, and every prose sentence earns its place. The 'USAGE EXAMPLES' block of raw user_input lines is mostly decorative and pads the definition slightly.

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

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

With an output schema present, return values need not be spelled out, and the description still notes that updated run details are returned. For a two-parameter mutation with full annotation coverage, only auth requirements are unaddressed, which is a minor 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 both parameters and the 30-second graceful-abort timeout are already documented in the schema. The description only gestures at 'gracefully' via an example, adding no syntax or semantic meaning beyond the schema. 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?

Specific verb (Abort) plus resource (Actor run) and a state qualifier ('currently starting or running'), which immediately distinguishes it from siblings like call-actor and get-actor-run. 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?

Explicit when-to-use ('stop a run that is taking too long or misconfigured') and an explicit no-op condition (terminal statuses such as SUCCEEDED, FAILED, ABORTED, TIMED-OUT). It does not name an alternative tool or describe prerequisites, so it falls 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.

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

Annotations already declare readOnly, idempotent, non-destructive, but the description adds real behavioral context beyond them: the summary vs. nextStep semantics, and that waitSecs blocks for up to 45s (default 30) before returning the current state. This is substantive added value, though it doesn't cover error/failure modes.

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 segmented into Returns/USAGE/EXAMPLES blocks. Every line carries information, though the two usage examples are somewhat redundant with the USAGE prose, adding minor 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?

With an output schema present and 100% parameter coverage, the description need only orient the agent, which it does fully: purpose, when to use, wait semantics, and concrete invocation examples. 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 coverage is 100%, so the baseline is 3, but the description goes further by framing waitSecs as a blocking/wait mechanism with its cap and default, and by describing what runId's run produces. Slight above-baseline value over 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?

States a specific verb and resource ('Get detailed information about a specific Actor run') and enumerates the returned result fields (status, storages, stats, summary, nextStep). It does not explicitly distinguish itself from siblings like call-actor or abort-actor-run, so it falls just short of the 5 benchmark.

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 USAGE block names the condition ('check the status of a run started by any Actor-running tool') and explains when to pass waitSecs > 0 to block until terminal. It gives clear context but stops short of explicit exclusions or naming the sibling to use for other run operations.

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 safety (readOnly, idempotent, non-destructive), so the description adds value by disclosing the default limit of 20, what clean=true does, and that results are the raw rows. Return-shape details are largely deferred to the existing output schema, which is appropriate.

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

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

Front-loaded with the core purpose and the anti-scope sentence, followed by short usage notes and examples. Slightly redundant in repeating the limit default and the clean flag across sections, but nothing wasteful enough to hurt.

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 read tool with full schema coverage and an output schema, the description supplies the purpose, trigger, and key defaults an agent needs. Pagination interaction (offset/limit) and flatten behavior are left to the schema, which is reasonable given the output schema exists.

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 in depth. The description only restates the default limit and clean=true semantics, adding little beyond the structured fields; baseline 3 applies.

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

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

States a specific verb and resource ('Get items (rows) from a dataset') and immediately delimits scope by saying it returns rows themselves, not metadata, counts, or schema. An agent can distinguish the intent 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 a clear trigger ('When the user provides a datasetId and asks to retrieve results, output, data, or rows, call this tool directly') plus a usage section and two concrete examples. It lacks explicit when-not guidance relative to any alternative, but the sibling list contains no competing dataset-read tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered elsewhere. The description earns credit for adding behavioral context beyond that: the 'requires the exact key name' precondition and the note that the response preserves the original Content-Encoding, which most clients decompress automatically — a real return-value trait callers would otherwise trip over.

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 key facts — scope, exact-key requirement, encoding caveat — are front-loaded in three tight sentences. The subsequent USAGE and USAGE EXAMPLES blocks are somewhat redundant with the first paragraph, costing a little efficiency.

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?

A two-parameter read tool whose annotations, 100% schema coverage, and output schema already cover safety, inputs, and return shape. The description closes the remaining gap with the Content-Encoding behavior, which is exactly the non-obvious detail an agent needs.

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%, including the keyValueStoreId resolution rules (name vs. username~name) and minLength constraints in the schema itself. The description only reinforces that the key must be exact, adding little semantics beyond what the schema already documents, 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 and resource ('Get the value stored under a specific key in a key-value store') and preemptively scopes it against a listing tool: 'a single record, not a listing of all keys.' An agent can immediately tell this is a point lookup, not an enumeration.

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 says when to use it ('when you need to retrieve a specific record (JSON, text, or binary)') and includes two concrete usage examples showing the store identifier formats. However, it never states when NOT to use it or names an alternative/sibling for enumeration, so the guidance is implied rather than comparative.

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 openWorldHint=true and destructiveHint=true, so the agent knows this touches external state, yet the description adds nothing about that: no billing/cost note for an Actor run, no runtime expectations, no mention that results are snapshots that vary by region and time. Those caveats live only in the input schema's description, not the tool description. The description merely restates that it calls the Actor and retrieves results, which is close to what the annotations and name already convey.

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

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

Two sentences: the wrapper statement first, then the actor capability blurb. There is no filler or marketing padding, and the substantive data list is front-loaded after the boilerplate. The 'This tool calls the Actor ... and retrieves its output results' lead-in is slightly redundant given the tool name, keeping 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?

An output schema exists and the input schema is fully documented, so return values and parameter formats need not be explained. What is missing is behavioral context the schemas don't supply: expected run duration, cost implications of running an Actor, and freshness/snapshot caveats for price data. For a 9-parameter open-world scraping tool, the description is adequate but thin.

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 9 well-documented parameters including sort enums, ship_to ISO codes, currency enums and a detailed waitSecs polling note. The description itself adds zero parameter meaning beyond that. Baseline 3 is correct: the schema does all the work and the description neither helps nor misleads.

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 resource and verb twice over: it runs the 'hirepulse/aliexpress-search-scraper' Actor and returns its results, and the actor blurb names the exact fields extracted (products, sale and original prices, discounts, orders, ratings, shipping signals, delivery estimates, SKU IDs, image galleries). That is far more specific than a generic 'scraper' label. It stops short of distinguishing this from sibling scrapers (google-jobs, google-ads-transparency) beyond the AliExpress domain, so a 4 rather than 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?

The only usage signal is the audience list 'built for e-commerce research, dropshipping, n8n workflows and AI agents', which implies context but gives no when-to-use conditions, prerequisites, or exclusions. Nothing tells the agent when to prefer this over a sibling scraper or when it is the wrong tool. Usage is implied, not stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, and the schema documents the per-company charge and waitSecs polling behavior. The description adds that runs are compared across executions for NEW/CLOSED tracking, which is useful context, but it never explains why a scraper is flagged destructive (it launches an Actor run and bills per company found) and its phrase 'retrieves its output results' understates the run-and-charge behavior.

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

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

The first sentence is boilerplate about calling an Actor, and the second is a dense, comma-heavy list that ends in platform filler ('JSON for n8n, Make and Apify MCP') which does not help tool selection. The substantive content (sources, hiring signals, change monitoring) is present but not 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 an output schema, full parameter coverage and annotations, the definition is workable, and it does convey sources and the cross-run monitoring concept. It omits material facts an agent should know before invoking: that Workday is unsupported, that a run is created and billed per company, and that first-run velocity signals are meaningless.

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% across all 14 parameters, so the schema already explains state_id, track_diff, output_mode, filters and max_jobs_per_company in detail. The description adds essentially nothing parameter-specific beyond 'by company domain', 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?

The description names a specific resource (job postings) and the exact sources it covers (Greenhouse, Lever, Ashby, Workable, Recruitee, SmartRecruiters) plus the access path (company domain), so an agent knows what the tool returns. It does not differentiate itself from the sibling hirepulse--google-jobs-scraper, which is a very similar job-scraping tool, so an agent must infer the distinction.

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 only implied through phrases like 'hiring signals for lead enrichment' and 'a job postings monitor for new and closed jobs across runs'. There is no explicit when-to-use versus when-not guidance, no mention of the Google Jobs sibling as an alternative, and no stated prerequisites (e.g., that a fixed state_id is needed for monitoring).

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 framing 'calls the Actor and retrieves its output results' usefully signals that this spawns an external run rather than reading stored data, and it discloses that source availability plus an intent estimate come back. However, annotations declare destructiveHint=true and openWorldHint=true for what reads like a pure research call, and the description never explains that tension, nor mentions credit cost, run persistence, or the waitSecs cap / nextStep polling path documented only in the schema.

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

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

Two sentences, no padding, and the informative content is front-loaded in the second sentence. The opening sentence ('This tool calls the Actor ... and retrieves its output results') is scaffolding that restates the tool name and earns little of its space, keeping this below 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?

An output schema exists, so return-value explanation is not required, and annotations plus the schema description carry safety and scope caveats. What is missing from the description is only the operational picture — that a run may return before completion at the waitSecs cap and that results must be polled — which the schema partially covers.

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 each parameter (domains, country, waitSecs, include_jobs, use_paid_upstream) carries its own detailed documentation, so the schema does the work. The description adds only the loose phrase 'by domain' and no additional semantics about batching, per-domain reporting, or cost of the paid-upstream flag, so baseline 3 applies.

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

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

Second sentence states a specific verb+resource: consolidate ATS hiring, Google Ads Transparency, website tech and email DNS signals into one JSON report per company domain. That is materially more specific than siblings like ats-job-pulse or google-ads-transparency-scraper, though the description never names those siblings to make the 'combined radar vs. single-source scraper' distinction explicit.

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 cases are named (account qualification, AI sales agents, n8n), which implies when to reach for it, but there is no when-not guidance and no reference to the single-signal siblings that are the obvious alternatives. The explicit exclusions ('Public mode does not measure SEO traffic or ad spend') live in the schema description, not here, so the tool description alone leaves the agent to infer scope.

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 destructiveHint=true and openWorldHint=true, so the description should explain what makes this destructive or what it costs; instead it asserts 'Fast, zero-cost native mode' without acknowledging that the call spawns an Actor run, may wait up to 45s (waitSecs), or that paid upstream data exists behind owner opt-in. No run lifecycle, polling/nextStep behavior, or per-run limits (100 domains) are disclosed in the description. With a destructive annotation in play, this leaves the agent materially under-informed.

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 sentences, but the first is boilerplate ('calls the Actor ... and retrieves its output results') and the second mixes useful capability detail with filler ('Perfect for n8n, Python, and AI agents'). It is short but not front-loaded on what an agent actually needs to decide and call.

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?

An output schema exists, so return values need not be explained, and the schema description already covers the public-mode caveats (no traffic/ranking/volume data). However, for a destructive, open-world actor-run tool the description omits cost/credit implications, run-lifecycle behavior and sibling routing, leaving real gaps at the description level.

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 all 9 parameters carry detailed descriptions, including the domains/url/domain aliasing, the 94-country enum, waitSecs semantics and the paid-upstream opt-in. The description adds nothing beyond that, so the baseline 3 applies — the schema does all the work.

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 resource and output set: technical SEO audit covering homepage metadata, canonical URLs, sitemaps, robots.txt, /llms.txt AI readiness and Chrome popularity tier. An agent can tell this is a site-audit tool rather than a keyword-volume or job-scraper sibling. It loses a point because the opening sentence is a generic 'calls the Actor and retrieves its output' wrapper that adds no distinguishing information.

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 itself contains no when-to-use or when-not-to-use guidance; 'Perfect for n8n, Python, and AI agents' is marketing, not routing criteria. It never mentions the sibling tools (e.g. keyword-search-volume, company-intent-radar) or the public-vs-paid mode choice that would change which tool/params an agent picks. Only the separate schema description hints at usage ('inspect a site before a technical SEO audit'), and that is not in the description field.

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, destructiveHint=true and openWorldHint=true, and the description is consistent with them (it triggers an Actor run, so not a pure read). Beyond that it adds only the generic framing 'calls the Actor ... and retrieves its output results'; it omits the cost model (per-result/per-domain charges), run duration, and the polling path — details that appear only inside parameter descriptions or not at all.

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 is front-loaded in the first sentence, but the second sentence's tail — 'for competitor ad research, brand monitoring, n8n, Make and Apify MCP' — is channel marketing that adds no decision value for an agent.

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?

An output schema exists, so return values need not be explained, and the schema carries the parameter detail. However, for a paid, destructive, long-running scrape with 11 parameters, the description says nothing about billing, run lifecycle, or that an empty result is not evidence a brand never advertises — that caveat is buried in the schema description instead of the tool description.

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 11 parameters (including enum values, waitSecs cap, only_new_ads semantics and paid-upstream gating) are already documented in the schema. The description adds no parameter meaning of its own, 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?

The description names a specific verb and resource: scraping Google Ads Transparency Center records by company domain, listing the returned fields (creatives, formats, advertisers, first/last shown dates). It does not differentiate from sibling scrapers (aliexpress-search, youtube-transcript, domain-seo-overview), so an agent must infer from the domain topic alone which scraper to pick.

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 offers use contexts ('competitor ad research, brand monitoring') but no when-to-use/when-not guidance relative to siblings, and no routing to get-actor-run or get-dataset-items despite the tool being an Actor invocation. The mode-selection guidance (summary vs ads) lives in the schema parameter descriptions, not the tool description.

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 readOnlyHint=false, destructiveHint=true and openWorldHint=true, but the description never addresses mutation/state impact, cost, or credential requirements. It does add genuine non-schema context: results come from public feeds rather than Google SERPs, and paid upstream sources are off by default. Per-result charging and wait/poll behavior are disclosed only in the schema, so the added value is moderate rather than strong.

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 sentences, reasonably front-loaded, with the SERP-vs-public-feed caveat placed early where it matters most. The integration sentence ('Use with n8n, Make or Apify MCP') is filler that does not help an agent decide or invoke, keeping it out of the top band.

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?

An output schema exists, so return values need no explanation, and all 10 parameters are fully described in the schema. The description supplies the crucial coverage caveat (public feeds, not Google Jobs SERPs) that an agent needs to avoid overpromising results. What is missing is cost/charging disclosure and explicit routing to alternatives, which are relevant given destructiveHint=true and a large sibling set.

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% across all 10 parameters, including detailed enum, language-per-country, and paid-source caveats, so the schema carries the burden. The description adds essentially no parameter-level detail beyond restating that output is JSON. Baseline 3 applies when the schema already documents everything.

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 concrete resource and mode of operation: search public job feeds by keyword or fetch company ATS jobs by domain, returning titles, employers, locations and apply links. That is specific enough to distinguish it from generic scrapers in the sibling list. The opening wrapper sentence ('calls the Actor ... and retrieves its output results') is boilerplate, and the claim of 'fetch company ATS jobs by domain' is partly walked back by the schema note pointing to ats-job-pulse for per-company coverage.

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 implies research use and warns that default results come from public feeds rather than Google Jobs SERPs, which is a useful scoping cue. But it gives no explicit when-to-use/when-not guidance and never names an alternative tool; the only routing advice ('ats-job-pulse is the better fit') lives in the queries parameter schema, not the description. 'Use with n8n, Make or Apify MCP' is integration marketing, not usage 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 already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, and the description is consistent with them (it triggers an Actor run). It adds a genuinely useful behavioral caveat — public mode returns no measured volume/CPC/difficulty and null fields — but omits the cost/billing implications of running the Actor and the async wait/poll behavior that the schema documents.

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 content is a reasonable length and the substantive actor description is present, but the opening sentence ('This tool calls the Actor ... and retrieves its output results') is reusable boilerplate that restates the title and eats front-loaded space. The useful scoping caveat lands in the final sentence rather than early.

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

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

With an output schema present and annotations covering the safety profile, the description needn't explain returns or safety. It adequately conveys purpose and the metrics limitation, but for a 10-parameter, credit-consuming Actor call it omits the run lifecycle (waitSecs/polling) and cost context an agent should weigh before invoking.

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 ten parameters are already documented in the schema, and the description adds no syntax or format detail beyond it. Its one semantic contribution is reinforcing that 'suggestions' mode yields no metrics, which loosely relates to the mode parameter. 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?

The actor description states a specific verb+resource: 'Generate Google Autocomplete keyword suggestions from seed phrases'. This distinguishes it from the sibling scrapers (aliexpress, google-jobs, youtube-transcript). However, the leading sentence is boilerplate meta ('calls the Actor ... retrieves its output results') and the tool name misleadingly implies search volume, which the description must then walk back.

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

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

It names use cases ('for SEO, content planning and keyword research') but gives no when-to-use/when-not guidance and names no alternative sibling tools. The mode/limitation notes are constraints rather than routing guidance, so an agent gets no help choosing between this and the other hirepulse scrapers.

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 readOnly=false, destructive=true, openWorld=true, but the description adds context annotations cannot: no YouTube API key required, it does not transcribe audio, captions are not guaranteed, and unavailable/blocked/captionless videos return explained outcomes. That sets accurate expectations for output failures. It does not address the surprising destructiveHint=true or the fact that a run is started, which leaves a small gap.

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 lead sentence is pure boilerplate about invoking an Actor, and the tail includes marketing filler ('No YouTube API key; works with n8n, Make and Apify MCP'). The useful content — bulk extraction scope and the no-transcription caveat — is buried mid-text rather than 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 a full input schema, an output schema, and annotations already supplied, the description only needs to frame purpose and limits — which it does, including the caption-availability caveat and error outcomes. Only the run-lifecycle/polling implication is left implicit.

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 the `videos` array, `language`, `waitSecs`, `use_paid_upstream` and `include_timestamps` all documented in detail including examples and charging semantics. The description adds nothing parameter-specific beyond 'optional timestamps,' 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?

The second sentence gives a specific verb and resource: 'Extract YouTube transcripts in bulk from videos, Shorts and live replays.' That is enough for an agent to distinguish it from siblings like google-jobs-scraper or ats-job-pulse. The first sentence is boilerplate ('calls the Actor ... and retrieves its output results') and does no differentiating work, but the net purpose is unambiguous.

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 names target scenarios ('for RAG, summaries and content research') and mentions integration contexts (n8n, Make, Apify MCP), which implies when to reach for it. However, there is no explicit when-not guidance and no routing between this tool and siblings such as get-dataset-items or get-actor-run, which a caller may also need for long runs.

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