LeoWorks Review & Lead Data Tools (via Apify MCP)

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?

With annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds valuable behavioral context: returns rows themselves, default limit of 20, and clean=true behavior. It also clarifies the nature of the return value beyond 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?

Well-structured with clear USAGE and USAGE EXAMPLES sections. Some redundancy ('Get items (rows)...' and 'Returns the rows themselves...') but overall efficient and front-loaded with 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 has 8 parameters, an output schema, and rich annotations, the description adequately covers key behaviors, usage triggers, and examples. It doesn't explain every parameter but relies on the schema for that, which is appropriate.

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 baseline is 3. The description adds extra meaning by explaining default limit (20) and the clean=true shortcut, which supplements the schema. It also provides examples for fields usage, though most parameter semantics are 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?

Description clearly states the tool gets items (rows) from a dataset and explicitly distinguishes it from metadata, counts, or schema. It names the exact resource (dataset items) and the action (get), and provides direct trigger phrases for when to use it.

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 use cases ('when the user provides a datasetId and asks to retrieve results...'), and clarifies what it is not for (metadata, counts, schema). However, it does not name alternative tools explicitly, only implies them.

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, closed-world behavior. The description adds genuine context beyond that: the exact key name is required, and the response preserves the original Content-Encoding with most clients decompressing automatically. That encoding note is real operational value an agent would otherwise not know.

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 scope, then a short behavioral note, then usage. The USAGE line slightly overlaps the first sentence, but the examples earn their space by showing realistic inputs. 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?

With an output schema present there is no need to describe return values, and the annotations carry the safety profile. For a two-parameter read tool, the description supplies everything else an agent needs: exactness of the key, allowed value types, and the encoding caveat.

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. The description still adds a semantic constraint the schema omits — that the key must be an exact match — and the examples show the 'username~my-store' form of the store ID, gently reinforcing the ID format.

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 (get) + resource (value under a key in a key-value store) with an explicit scope boundary: 'a single record, not a listing of all keys.' None of the sibling tools overlap with this resource, and the anti-scope clause removes any ambiguity about whether it enumerates keys.

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 line gives a clear triggering condition — retrieving a specific record (JSON, text, or binary) — and two concrete examples anchor it. It lacks explicit when-not-to-use guidance or named alternatives, but no similar sibling exists to route against.

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 and destructiveHint, and the description adds genuinely useful context beyond them: no login required, ~8 minutes per 1,000 reviews, and pay-per-review cost. It does not explain the destructiveHint=true flag (a paid, credit-consuming run), leaving the agent to infer why the tool is marked destructive.

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 Actor description is dense and front-loaded, packing scope, alternative, input form, auth, runtime and pricing into a few clauses. The leading 'This tool calls the Actor ... and retrieves its output results' sentence is pure boilerplate that earns no place, keeping it just below top marks.

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 no explanation, and the 22 parameters are fully described in the schema. The description covers the key operational facts an agent needs before a paid, long-running scrape, though it doesn't mention the waitSecs/nextStep polling behavior or the monitorKey comparison feature.

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 22 parameters, so the schema already documents country, keywords, star filters, pricing, proxy and the rest. The description adds only 'productUrls or IDs' for the required argument, which the schema already states — 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 description names a specific verb+resource — scraping AliExpress reviews and analyzing them (translation, stars, country, photos, complaints, sentiment) — and explicitly distinguishes itself from the sibling keyword-search scraper. The one generic sentence about 'calls the Actor and retrieves output' is boilerplate, but the Actor description that follows carries the real purpose.

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 the selecting condition ('Use for known products') and names the alternative for the other case ('for keyword search use leoworks/aliexpress-search-scraper'), plus the accepted input form (product URLs or IDs). An agent can route between this tool and its closest sibling without opening either schema.

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 genuinely useful behavior beyond the annotations: 'No login, ~6 s/20 results, rank history in your key-value store. Pay per result' discloses auth requirements, latency, cost model, and the fact that the tool persists state into the user's key-value store — which explains the destructiveHint=true for what looks like a read-only scrape. It stops short of saying what happens to the KV store on repeated runs or what the run-status/polling behavior is at the waitSecs cap.

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 text is compact and wastes few words, but it reads as a semicolon-chained run-on with no clear separation between purpose, usage, and operational notes. The lead sentence is boilerplate that delays the useful content rather than front-loading it.

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 explained, and the description covers the remaining gaps an agent would worry about: no login, approximate runtime, per-result pricing, and persistent rank history. Given 14 parameters and a dual search/rank mode, a bit more guidance on choosing between the two modes would make it fully complete.

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 baseline is 3. The description adds only a light nudge — 'keywords (+ tracked products)' hints that supplying tracked products switches to rank mode — while sort, country, currency, maxResultsPerKeyword, and the proxy parameters are left entirely to 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 names the concrete resource and outputs (AliExpress search results with rank, price, sold count, and flagged ads) and explicitly contrasts itself with the reviews sibling. The opening line ('This tool calls the Actor ... and retrieves its output results') is generic wrapper boilerplate, but the actor description that follows carries genuine purpose detail.

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 for search, price and sold count; for reviews use leoworks/aliexpress-reviews-classifier' gives an explicit when-to-use and a named alternative, which is exactly what an agent needs to pick between the two AliExpress tools. It does not state exclusions beyond reviews, and mode selection (search vs. rank) is deferred to the trackProducts parameter rather than explained here.

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, but the description adds substantial context annotations cannot carry: per-review billing (~$6/1k collector, $0.0005 classified), Free-plan caps, no-login/no-cookies collection, and the ~100 reviews/product ceiling. It never explains the destructive/state-creating nature, which is the one notable 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?

Two tight sentences followed by the compact actor summary; the primary function is front-loaded before the sourcing and pricing details. It is dense but every clause carries routing or cost information rather than 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 a 30-parameter, zero-required, output-schema-backed tool, the description supplies the routing, billing, and sourcing facts an agent needs before committing to a paid run. Return values are covered by the output schema, so remaining detail lives in the right place.

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 30 parameters, so the schema already documents inputs thoroughly, including the mutual exclusivity of products/datasetId/texts. The description restates the input modes and cost tiers rather than adding new parameter meaning, so a baseline 3 is warranted.

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 ('calls the Actor leoworks/amazon-review-classifier and retrieves its output'), and the actor summary pinpoints the function: complaints, return reasons, praise, sentiment. It also names the sibling to use for a different marketplace (AliExpress), so an agent can route 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?

Explicitly routes AliExpress traffic to leoworks/aliexpress-reviews-classifier and lays out the three input modes (products, datasetId, texts) with cost implications. It stops short of a full when-not-to-use statement, but the branching guidance is clear and actionable.

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 carry the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the bar is lower. The description adds genuinely useful behavioral context beyond them: throughput ('~200 sites/6 s') and a cost model ('pay per company'), which matter for a paid, stateful Actor run. It does not explain the destructive flag directly.

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 classification scope, then usage routing, then input/cost notes. The opening line ('This tool calls the Actor ... and retrieves its output results') is boilerplate but short. Overall efficient, one minor piece of 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 a complex 11-param classifier with an output schema (so return values needn't be explained) plus rich annotation coverage, the description supplies purpose, scope, an alternative, both input modes, and cost/rate context. Nothing essential for correct invocation is missing, though destructive/cost semantics could be spelled out further.

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 documents all 11 parameters in depth. The description only adds a brief summary of the datasetId/pages relationship ('crawled pages (grouped by site) or pages JSON'), which is already covered by the schema. 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 and resource — 'Classify company websites from your crawl' — and enumerates the outputs (industry, B2B/B2C, reach, ICP fit scoring with tier and reason). It explicitly differentiates from the sibling it could be confused with: 'for Google Maps places use leoworks/google-maps-lead-qualifier.' An agent can pick this 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 ('Use for company sites') and names the concrete alternative for the Google-Maps case. It also clarifies the two valid input modes (datasetId vs pages JSON). No explicit 'when-not-to-use' beyond the one sibling pointer, so it stops 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 readOnlyHint=false, openWorldHint=true, destructiveHint=true. The description adds genuine non-schema context — throughput (~3 s/60 places) and cost (~$6/1,000, with 'compass billed to you'). It does not explain what is actually destroyed/consumed or any auth requirements, so it is useful but not rich.

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, front-loaded with the action and then the actor's purpose and cost/perf facts. Dense and mostly free of waste, though the 'Actor description:' framing is slightly mechanical.

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 re-explained, and the description still summarizes the output (score, tier, reason). For a 25-parameter, paid, open-world tool it covers routing, inputs, cost and speed adequately, leaving only deeper behavioral detail 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% and there are 25 parameters, so the schema carries the parameter detail. The description only summarizes the high-level input combinations (icp + places/datasetId/search terms + location) without adding format or constraint 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?

The description states a specific verb+resource ('calls the Actor leoworks/google-maps-lead-qualifier and retrieves its output results') and the actor's purpose ('lead scoring for ICP fit (score 0–100, tier A–D, reason)'). It also names a sibling (review classifier) as the alternative for a different task, so an agent can distinguish it. It falls short of 5 because it doesn't contrast against the many other classifier siblings.

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 routes one scenario explicitly ('For reviews use leoworks/google-maps-review-classifier') and lists the accepted input combinations ('icp text + places, datasetId or search terms + location'). It gives clear context for invocation but no explicit when-not-to-use beyond the review case.

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 (readOnlyHint=false, destructiveHint=true, openWorldHint=true), and the description adds real behavioral context beyond them: timing (~25 s/place) and cost (~$1.10/1,000, with the compass Actor billed to the caller). That cost/billing disclosure is valuable for a paid, externally-billed tool.

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

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

Short and front-loaded with the core action, then supporting routing/cost facts. Every sentence carries information, though the mix of Actor-wrapper boilerplate and parameter hints makes it slightly dense.

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 explained, and the description provides the missing routing, cost, and sibling-alternative context for a 23-parameter tool. Adequate and complete enough for an agent to select and configure 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 the schema already documents all 23 parameters. The description adds only light routing hints (places vs datasetId), so the 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?

The description states a specific verb+resource: it calls the 'leoworks/google-maps-review-classifier' Actor and retrieves its output, and summarizes the analysis domain (complaints, praise, sentiment, reply queue). It also distinguishes itself from the lead-qualifier sibling. Clear, though the purpose statement is somewhat buried under cost/parameter routing notes.

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 an alternative for a related task ('For leads use leoworks/google-maps-lead-qualifier') and clarifies the input routing ('places = Maps URLs/IDs or names + location; datasetId = reviews'). It lacks an explicit when-not-to-use statement, but the routing guidance is genuinely actionable.

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 and destructiveHint=true, which is misleading for what is essentially a classification read operation. The description adds useful throughput context (~100 reviews/5 s, pay per review, auto-detection of datasetId/texts), partially offsetting the annotation mismatch. However, it does not clarify the destructive-hint implication or the write/return profile.

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 routing rule, then throughput and pricing. Slightly dense but no filler sentences; every clause about language, inputs, and cost is useful.

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 classifier with an output schema and rich schema descriptions, the description covers purpose, language routing, input options, throughput, and cost. It omits detail on the output format, but the output schema and per-parameter descriptions cover that. The mismatch with the destructive annotation is the one notable gap.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters thoroughly. The description only adds the auto-detection behavior for datasetId/texts and the pricing model, which is marginal over what the schema provides. Baseline 3 is appropriate 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?

The description states a precise verb and resource — classify Japanese reviews into complaint types, sentiment, and purchase motive — and explicitly distinguishes itself from the sibling leoworks/korean-review-classifier by language. An agent can route by language 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?

It clearly states when to use this tool (Japanese reviews) and names the alternative for Korean. It does not spell out when-not to use it versus, say, the amazon or google-maps review classifiers, but the language scoping is a strong routing signal.

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 safety/open-world profile is covered structurally. The description adds genuinely non-redundant behavior: the billing model ('pay per job'), the throughput ('~180 jobs/9 s'), and that some inputs are skipped without charge (mentioned in schema-side params too). It does not explain that a run is created or how results are surfaced, but billing and rate context is meaningful beyond the 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?

It is compact and front-loads the relevant information (purpose, alternative sibling, input source, cost). The middle fragment 'Job posting classifier.' is a near-tautological restatement of the title, and the 'Actor description:' prefix is mechanical, but overall there is little wasted text.

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, the description does not need to explain return values, and it correctly defers to the schema for the 15 parameters. It covers domain, alternative tool, input source and cost/rate. The main gap is that it omits the jobs-or-datasetId input requirement, which an agent needs to call the tool successfully given 0 required parameters.

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 15 parameters in detail; baseline is 3. The description adds only one clause of param meaning ('datasetId = jobs scraper output, or jobs JSON'), which mildly clarifies datasetId but duplicates the schema note 'Use this OR Job postings'. No additional syntax or defaulting semantics are supplied.

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 identifies the Actor being invoked and the resource domain: filtering/classifying job postings from LinkedIn, Indeed or Glassdoor by work mode, visa sponsorship and USD salary. It also distinguishes itself from a sibling ('for company sites use leoworks/company-website-classifier'), so an agent can tell it apart from other classifiers. The boilerplate opener ('calls the Actor ... retrieves its output results') is generic, but the embedded actor description carries the real purpose.

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 one explicit routing rule ('Use for job data; for company sites use leoworks/company-website-classifier') and states the cost/throughput profile ('~180 jobs/9 s, pay per job'). However it never states the precondition that the caller must supply either the jobs payload or a datasetId, and there are no when-not-to-use conditions for the many filtering parameters. Usage is implied rather than fully spelled out.

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, so the safety profile is covered structurally. The description adds genuinely useful context beyond that: no login required, rank history is written to the caller's key-value store, and billing is per item. It does not explain what the 'destructive' aspect actually is, nor run lifecycle/polling behavior, though the waitSecs parameter covers the latter.

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 sentence is dense and front-loaded with the domains and the sibling routing, followed by short operational facts (0 = rankings only, no login, KV store, pay per item). The only waste is the 'calls the Actor ... and retrieves its output results' preamble, which conveys nothing an agent needs.

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 20-parameter Actor wrapper with an output schema and full annotation coverage, this is complete enough: the agent learns the source sites, the ranking-vs-review distinction, the zero-review escape hatch, the cost model, auth requirements, and where history is persisted. Return-value shape is handled by the output schema, so nothing essential 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% and the 20 parameters carry detailed per-field descriptions (including enum titles and Korean labels), so the schema does the heavy lifting and the baseline is 3. The description's only parameter-level addition, 'reviewsPerProduct 0 = rankings only', restates what the schema already says, so no credit above baseline.

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 the concrete resource set: Olive Young Global and Amore Mall (아모레몰) bestseller rankings plus review collection. The opening boilerplate ('calls the Actor ... and retrieves its output results') is generic, but the Actor description immediately delivers a specific verb+resource that an agent can act on and distinguishes it from the review classifiers.

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 explicitly routes the agent: 'Use for rankings; for existing reviews use leoworks/korean-review-classifier', and clarifies 'reviewsPerProduct 0 = rankings only'. That is a real use/exclusion split with a named alternative. It stops short of stating other conditions (e.g. when to prefer the naver-shopping-rank-tracker sibling or when rankings are unnecessary).

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

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

Annotations cover the safety profile (readOnly=false, openWorld=true, destructive=true), so the description is not required to explain mutability. It adds genuinely non-annotation context: throughput (~100 reviews/5 s) and a pay-per-review cost model, which matter for an agent deciding whether to batch. It does not address the destructiveHint or the async polling pattern, 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?

Dense and mostly front-loaded — language scope, sibling routing, input modes, throughput and cost all in a few lines. The redundant "This tool calls the Actor ... and retrieves its output results" sentence adds no information but is short.

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-required-param Actor wrapper with a full output schema, the description supplies what the schema cannot: language applicability, sibling routing, cost model, and throughput. Return-value semantics are correctly left to the 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?

Schema description coverage is 100%, so all 13 parameters are already documented in the schema, including the auto-detect behavior of textField and summaryGroupField. The description only restates the two primary input modes (datasetId or texts), 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?

The boilerplate opener ("calls the Actor ... and retrieves its output results") is a tautology, but the embedded Actor description gives a specific verb+resource: classify Korean reviews for complaint types, sentiment, and purchase motive. It clearly separates itself from the Japanese/Spanish/AliExpress classifier siblings by naming the language domain.

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 for Korean; for Japanese use leoworks/japanese-review-classifier" gives an explicit routing rule to the nearest sibling. It does not state when-not to use it (e.g. non-review text, mixed-language batches), but the primary selection decision is answered.

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 and destructiveHint=true, and the description adds genuinely new context: no login required, ~10 s per 2 queries, pay-per-query cost, and that results are polled/returned at the waitSecs cap. These cost, auth and latency facts are exactly what annotations cannot 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?

The lead sentence ("This tool calls the Actor ... and retrieves its output results") is boilerplate, but the Actor description that follows is dense and front-loaded with the discriminating facts. Overall it is appropriately sized with little waste.

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

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

For a 10-parameter wrapper with an output schema, the description covers purpose, routing, cost, latency and auth while the schema and output schema carry parameter and return detail. Proxy configuration, concurrency and healthCheck are left to the schema, which is acceptable.

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. The prose adds only "queries in Korean" and "brandNames flag mentions", both of which are already effectively stated by the schema, so it does not meaningfully extend parameter meaning.

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 action (calls the Actor and retrieves its output) and then states the Actor's actual purpose: tracking brands in the Naver AI briefing with answers, cited sources, and AI ads. It explicitly distinguishes itself from the sibling leoworks/naver-shopping-rank-tracker, 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?

"Use for AI answers; for shop ranks use leoworks/naver-shopping-rank-tracker" gives a clear when-to-use plus a named alternative with the condition that selects it. What is missing is guidance on the other siblings or on prerequisites beyond "no login" (e.g. Apify proxy/account expectations), which keeps it short of a full 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 only declare readOnly=false, destructive=true, openWorld=true; the description adds genuinely useful operational context: no login required, roughly 6 minutes per 1,000 posts, and pay-per-post billing. That cost/latency/auth profile is exactly what an agent needs before committing, though it never explains the destructiveHint in terms of credits consumed or dataset writes.

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 compact sentences with no filler, and the pricing/latency constraints are stated up front. The opening clause about calling the Actor and retrieving results is wrapper boilerplate that could be dropped.

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 14-parameter Actor with full schema coverage and an output schema, the description covers purpose, cost, runtime, auth, language of queries, and the nearest alternative. It omits any hint about polling behaviour when the wait cap is hit, but waitSecs and nextStep in the schema already handle 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 nearly every parameter is already documented in detail, including the judged-posting charges and maxPostsPerQuery limits. The description only adds that queries are Korean keywords, which duplicates the schema, 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 (Naver Blog posts by keyword) and the analyses performed (sponsored post detection, sentiment, brand mentions), which is far more than the tool name conveys. It is slightly muddied by the boilerplate opener about calling the Actor, but an agent can still tell what it does and how it differs from leoworks--naver-shopping-rank-tracker.

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

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

Explicitly says 'Use for blog posts' and routes shop-rank needs to leoworks/naver-shopping-rank-tracker, so the main sibling ambiguity is resolved. It also notes queries must be Korean keywords. There is no guidance on when not to use it beyond that one sibling, 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?

The annotations are already rich (readOnlyHint=false, destructiveHint=true, openWorldHint=true). The description adds real context beyond them: no login, 3–10 s per keyword, pay-per-keyword billing, and rank history persisted in a key-value store. However, with destructiveHint=true declared, an agent gets no word on what is actually mutated or how the key-value store is written — the description never addresses that risk surface.

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 dense but front-loaded: the Actor identity and what it returns come first, then the sibling routing rule, then operational constraints. Semicolon-run-on phrasing ('No login, 3–10 s/keyword, rank history in your key-value store. Pay per keyword.') is slightly terse but every sentence 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?

For a 10-parameter Actor wrapper with a full output schema and 100% schema coverage, the description supplies exactly what the schema cannot: cost model, runtime, auth requirements, sibling routing, and history behavior. Given annotations already declare the safety profile and the output schema exists, this is close to complete; only the async polling/nextStep flow is left entirely to the 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?

Schema coverage is 100%, so the heavy lifting is already done by the schema — including the detailed targets description, waitSecs polling behavior, and rankHistoryStore semantics. The description only echoes 'targets = keyword + product URL/ID/store', which is a helpful orientation but not new information. 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 the exact Actor and states what it returns: organic rank 1–35, ad slot, and price per keyword for Naver Shopping. It also explicitly separates itself from the sibling naver-blog-brand-monitor. The only weakness is the generic wrapper phrasing in the first sentence, which restates the tool name instead of adding meaning.

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 an explicit routing rule ('Use for ranks; for blogs use leoworks/naver-blog-brand-monitor') and notes you need no login and should schedule runs to build rank history. It never states when NOT to use it (for example, for product detail scraping or price monitoring at scale), so it falls 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.

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=true, so the safety profile is carried structurally. The description adds genuinely useful context beyond that: throughput (~100 comments/4 s) and cost model (pay per comment), which is exactly the kind of rate/pricing disclosure that helps an agent plan a call. It stops short of explaining why destructiveHint is set (i.e. that a billable Actor run is created).

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?

Reasonably short and front-loaded, but the opening sentence ("calls the Actor ... and retrieves its output results") is wrapper boilerplate, and the platform list is redundantly repeated ("Instagram comments sentiment and TikTok comments analyzer") as SEO padding rather than new 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?

An output schema exists and schema coverage is 100%, so return values and most parameter meaning need not be restated. The description supplies purpose, the sibling alternative, and cost/throughput, which is close to complete for a 22-param classification Actor, though the destructive annotation remains unexplained.

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 22 parameters, so the schema does the heavy lifting and the baseline is 3. The description only restates the datasetId/texts choice and text auto-detection, adding nothing the schema does not already say.

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 names a specific verb and resource (classify Instagram, TikTok, Facebook, YouTube comments) plus the outputs it produces (buying intent, sentiment), and explicitly distinguishes itself from the sibling review classifiers. An agent can tell what it does and when it is the wrong 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?

"Use for comments; for reviews use leoworks/korean-review-classifier" gives an explicit when-to-use and a named alternative. The guidance is incomplete because the sibling list contains many other review classifiers (amazon, aliexpress, japanese, spanish, google-maps) that are not mentioned, so the routing rule is only partially drawn.

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 readOnlyHint=false, but the description frames the tool as calling an Actor and 'retrieving its output results,' never explaining what is mutated or consumed. It does add value the annotations lack — throughput (~100 reviews/5 s), a pay-per-review cost model, and Beta status — which keeps it above a bare baseline.

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 leading sentence ('This tool calls the Actor "leoworks/spanish-review-classifier" and retrieves its output results. Actor description: ...') is boilerplate meta-text that delays the useful content. The remainder is dense and front-loads the classification purpose and language routing, but the opening wastes space.

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

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

With an output schema present and full schema coverage, the description does not need to explain return shapes; it correctly focuses on purpose, language routing and cost. It leaves the destructive behavior unexplained, which is the one meaningful gap for a tool flagged destructive.

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 13 parameters are documented in the schema already. The description only restates the two main input modes ('datasetId (text auto-detected) or texts') without adding syntax or semantics beyond the schema, 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: classify Spanish reviews into complaint types, sentiment and purchase motive, with the MercadoLibre context. It also distinguishes itself from the sibling korean-review-classifier by naming the language routing explicitly, so an agent can select it 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?

Gives a clear when-to-use signal (Spanish) and points to the concrete alternative (leoworks/korean-review-classifier for Korean; datasetId or texts as input modes). It stops short of covering the other classifier siblings (Japanese, Amazon, Google Maps, social comment), so the routing map is incomplete but still actionable.

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