LeoWorks Data Tools — Naver, K-beauty & AliExpress

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond the annotations: the call is a no-op for SUCCEEDED/FAILED/ABORTING/ABORTED/TIMED-OUT runs, and the response returns the updated run details. It does not mention permission requirements or 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 action and its status preconditions before the USAGE block, and no sentence is wasted. The USAGE EXAMPLES lines are thin (one is a bare restatement of the required runId) but the graceful variant does demonstrate a real parameter usage.

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 detailed, and the description correctly just notes that updated run details come back. Purpose, preconditions, and usage are all covered; only permission/auth context is missing for a destructive, openWorld=false operation.

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 both parameters (runId, gracefully with its 30-second timeout) are fully documented in the schema, so the baseline is 3. The description adds little parameter meaning beyond the example 'Gracefully abort run y2h7sK3Wc', which only loosely illustrates the gracefully flag.

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 ('Abort an Actor run') and narrows scope with the precondition 'currently starting or running', which makes the operation unambiguous. It never names a sibling such as get-actor-run to contrast against, but the destructive abort semantics are self-evidently distinct from the read-only tools in the sibling list.

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

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

'Use when you need to stop a run that is taking too long or misconfigured' gives a clear triggering condition, and the status no-op list functions as an implicit when-not-to-use rule for terminal runs. No alternative tools or host-level prerequisites (auth, workspace scoping) are offered, so it stops short of a full routing guide.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the blocking semantics and 45s cap of waitSecs, the meaning of summary (describes the past) and nextStep (prescribes one interpolated follow-up), which an agent needs to interpret the response.

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

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

Front-loaded with the purpose, then USAGE, then examples, with every line carrying information: field list, summary/nextStep semantics, and the waitSecs contract. No filler sentences, and the examples are short and directly actionable.

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, yet the description usefully characterizes summary and nextStep so the agent can act on them. Purpose, parameters, blocking behavior and examples are all covered; only auth/permission prerequisites for reading another Actor's run are unstated, 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 coverage is 100%, so both parameters are already documented in the schema with min/max/default and terminal-state enumeration. The description's waitSecs line ('0-45, default 30, waits up to that many seconds for terminal status') largely restates the schema, adding no syntax or format beyond it, 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 gives a precise verb+resource ('Get detailed information about a specific Actor run') and enumerates the returned fields (status, storages, stats, summary, nextStep). It does not explicitly contrast itself with the sibling abort-actor-run, but the phrasing 'a run started by any Actor-running tool' makes its read-only inspection role clear.

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 section states when to reach for it ('check the status of a run started by any Actor-running tool') and how to make it block via waitSecs > 0, reinforced by two concrete user_input examples. It stops short of stating when NOT to use it (e.g. versus abort-actor-run or a listing tool), so it is clear context without exclusions.

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 establish readOnlyHint, idempotentHint, and destructiveHint as false. The description adds valuable behavioral context beyond this: the exact key name requirement and the preservation of Content-Encoding with automatic client decompression. No contradictions with annotations.

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

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

The description is well-structured with a concise opening definition, a short behavioral note, and clear usage examples. Every section earns its place without unnecessary fluff.

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 simple two-parameter read-only tool with full schema coverage, an output schema, and strong annotations, the description covers the essential context: how to target a record, what to expect (Content-Encoding), and when it applies. The sibling context also helps differentiate it from listing operations.

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?

Input schema coverage is 100%, so the schema already documents both parameters. The description adds usage examples and the 'exact key name' requirement, but these are minimally additive beyond the schema's own property descriptions.

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

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

The description uses a specific verb and resource: 'Get the value stored under a specific key in a key-value store.' It also distinguishes itself by explicitly stating this is 'a single record, not a listing of all keys,' which separates it from sibling tools like get-dataset-items.

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 provides a clear usage context: 'Use when you need to retrieve a specific record (JSON, text, or binary) from a store.' It does not name alternative tools explicitly, but the 'not a listing of all keys' phrase gives implicit exclusion guidance for listing-style 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 declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is partially covered. The description adds real context ('No login', AI classification is optional and enriches each review with complaint type/sentiment/motive plus a per-product summary), but it omits the per-review charging model and the fact that runs are asynchronous and may return before completion, both of which are operationally important.

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 with the substantive information (what is scraped, what classification adds, no login) front-loaded. The opening boilerplate 'calls the Actor ... and retrieves its output results' is filler that repeats the tool name.

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

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

With 12 parameters fully described in the schema and an output schema present, the description does not need to enumerate fields or return values. It covers the data surface and the optional classification mode adequately; the main gap is not flagging the cost-per-review and polling workflow that the schema mentions only in scattered parameter descriptions.

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; every parameter (productUrls, reviewFilter, classifyReviews, reviewsPerProduct, proxies, etc.) is already documented in the schema. The description adds no format or default detail beyond what the schema provides.

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 ('Scrape AliExpress product reviews – text, English translation, star rating, date, buyer country, option (SKU) and photos') and adds the optional AI classification layer, so an agent understands the output scope. It does not explicitly differentiate itself from close siblings such as leoworks--aliexpress-search-scraper or leoworks--korean-review-classifier, so it falls short of a 5.

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

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

There is no statement of when to choose this tool versus the AliExpress search scraper or the Korean review classifier, nor any prerequisite or exclusion guidance. The only routing hint ('follow `nextStep` to poll via get-actor-run') lives in the waitSecs schema field, not the 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 already declare openWorldHint=true and destructiveHint=true, so the safety profile is partly covered. The description adds useful context ('No login', ads flagged, up to 60 pages), but does not disclose why the tool is destructive (credit consumption per result vs per keyword, actor-run launch) nor that it may return before the run finishes at the waitSecs cap. 'Retrieves its output results' slightly oversells synchronous behavior, though the schema's waitSecs/nextStep text corrects it.

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 platform and the scraped fields; nothing is redundant or padded. The opening 'calls the Actor ... and retrieves its output results' wrapper is the only dead weight.

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 schema covers parameters and run polling. What is missing for a 14-parameter, credit-consuming actor is any note about cost model (per-result vs per-keyword) and the asynchronous run lifecycle, both of which matter for correct invocation but are only discoverable inside 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 description coverage is 100%, so the schema already documents all 14 parameters including defaults, enums and the rank-mode trigger. The description only gestures at a couple of concepts (rank mode, ads flagged) without adding syntax or semantics beyond 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 states a concrete verb and resource ('Scrape AliExpress search results for any keyword') and enumerates the returned fields (rank, title, price, discount, sold count, rating, ship-from, ads), plus the two operating modes (search vs rank). It is clear enough to distinguish from the AliExpress reviews classifier and Naver trackers by platform and data type, though the leading boilerplate sentence ('calls the Actor ... retrieves its output results') adds nothing.

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 usage via the mode split ('Rank mode tracks where your products rank ... over time') and 'No login', but never states when to pick this tool over the sibling rank trackers or when rank mode is appropriate versus plain search. The concrete trigger (setting trackProducts) lives only in the schema, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, lowering the disclosure bar. The description adds the useful behavioral fact that no login is required, but it does not explain the run lifecycle, the per-review/per-ranking-item charging that the schema mentions, or why the operation is 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?

Two tight sentences that front-load the actor identity and then the capability summary; no padding. Slightly boilerplate in the first clause ('This tool calls the Actor ... and retrieves its output results'), but nothing wasteful.

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 described, and the 20-parameter schema is fully documented. The description covers sources, review collection and AI classification adequately, though it omits the asynchronous run/polling behavior that an agent needs for long runs.

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 20 parameters, so the schema fully documents names, enums, defaults and trade-offs like cost and proxy behavior. The description adds no parameter meaning of its own, so the baseline of 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 gives a concrete verb+resource: tracking K-beauty bestseller rankings on Olive Young Global and Amore Mall and collecting reviews with optional AI classification. That is specific and understandable. It does not, however, differentiate itself from siblings such as leoworks--naver-shopping-rank-tracker or leoworks--korean-review-classifier, 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?

There is no when-to-use guidance, no mention of when not to use it, and no reference to any alternative tool. The 'No login' note is a fact about the actor, not usage guidance. The agent gets no help choosing between this and the other ranking/review siblings.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is partly structured. The description adds only 'no prompts, no LLM key' as a behavioral trait, and does not disclose that this launches a billable Actor run, its cost, or auth/rate-limit characteristics. With annotations covering part of the burden, this is adequate but thin.

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 actual classification capability and compact overall. The first clause ('calls the Actor ... and retrieves its output results') is boilerplate that restates the name, but the total length is small and nothing is bloated.

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 13 parameters with full schema coverage, an output schema, and annotations, the description covers the essential purpose and the source platforms. It leaves the billable-run behavior implicit, but the return format is handled by the output schema and parameter behavior by the schema, so it is largely complete for correct invocation.

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

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

Schema description coverage is 100%, so every one of the 13 parameters is already documented in the schema (texts vs datasetId, idFields, summaryGroupField, complaintThreshold, etc.). The description adds no parameter-level meaning beyond what the schema provides, which is the baseline 3.

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

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

The description names a specific verb (classify) and resource (Korean customer reviews from Coupang, Olive Young, Naver Shopping/Place) and states the output categories (complaint types, sentiment, purchase motive with probabilities). This distinguishes it from siblings like the Aliexpress classifier and the ranking/monitor tools. The opening boilerplate about calling the Actor adds no value but does not obscure the 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 implies context ('Korean review sentiment analysis for any review scraper's dataset') which suggests when it is applicable, but there is no explicit when-to-use vs the sibling aliexpress-reviews-classifier or other classifiers, and no exclusions. Usage is left to inference.

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

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

Annotations already declare openWorldHint=true and destructiveHint=true, so safety behavior is partly covered. The description adds useful context ('No login') and confirms it returns Actor output. However, it does not disclose that this is a scraping run subject to proxy fallback, wait caps, or that destructiveHint is flagged despite being a read-style monitor.

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

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

The description is short and front-loads the Actor call before the capability summary. The boilerplate first sentence adds little, but the overall length is appropriate and nothing is padded.

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

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

With an output schema present and 100% schema coverage, the description only needs to convey purpose and usage context, which it largely does. The main gap is the absence of when-to-use guidance relative to sibling monitors.

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 documented in the schema itself (including waitSecs batching behavior and brand/competitor limits). The description adds no parameter-level meaning beyond that, 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 the specific Actor and states its function: tracking a brand in Naver's AI briefing and capturing the answer, cited sources, ads, and related questions. This clearly differentiates it from siblings like naver-blog-brand-monitor or naver-shopping-rank-tracker. The opening wrapper sentence ('calls the Actor... and retrieves its output results') is generic boilerplate, 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?

The description never states when to choose this tool versus alternatives such as the other leoworks brand/review monitors. It implies a GEO/brand-tracking use case but gives no explicit trigger, prerequisites, or exclusions. An agent must infer its fit from the capability text alone.

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 the safety profile (openWorldHint=true, destructiveHint=true, readOnlyHint=false), so the description need not repeat it. It adds useful behavioral context — posts are labeled sponsored/self-paid with evidence, plus sentiment and brand mentions, and no login is required — but says nothing about billing/credit consumption or long-run polling, which matter for a paid Apify Actor.

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, well-sized, with the core function front-loaded after a short meta clause. The opening 'calls the Actor ... and retrieves its output results' is boilerplate filler, but nothing else is wasted.

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 tool with an output schema, return values need no explanation, and the description covers the scraping scope and what each result contains. The main omission is cost/credit behavior for the paid judgments, but annotations and schema carry most of the remaining burden.

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 14 parameters, so the schema already documents every field (queries, judge, brands, date range, proxy options). The description adds only indirect meaning ('posts by keyword' maps to queries, the labels map to the judge flags) and no syntax or defaults, making the baseline 3 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: it queries Naver Blog posts by keyword and labels each one sponsored/self-paid with sentiment and brand mentions. The Naver Blog scope cleanly distinguishes it from siblings like naver-shopping-rank-tracker and korean-review-classifier. It stops short of naming a sibling alternative, so it does not fully earn 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 description implies the use case (Korean social listening / brand monitoring on Naver Blog) and notes 'no login,' but never states when to pick this over siblings such as korean-review-classifier or kbeauty-ranking-review-monitor, nor any exclusions. Usage is inferable but not 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 declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, and the description adds real context beyond them: 'No login' (auth requirement), per-item charging for topCompetitors ('competitor-item'), and 'No extra charge' plus stateful behavior for rankHistoryStore (previousOrganicRank/rankChange/isNew persisted across runs). The destructive hint is implicitly explained by that key-value-store write, though the description never states the write explicitly.

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

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

Two sentences plus a compact Actor blurb, front-loaded with the call semantics and immediately followed by the substantive purpose. There is minor redundancy in the boilerplate first sentence, but nothing is padded.

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

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

With an output schema present, return values need no explanation, and the description covers purpose, auth, cost model, and scheduling. The remaining gap is selection guidance against the generic siblings (get-actor-run, get-dataset-items), which the waitSecs/nextStep polling note in the schema partially covers but the description does not reinforce.

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 10 parameters, including nested targets and proxyConfiguration, are documented in the schema itself. The description adds no syntax, format, or default information beyond what the schema already provides, 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 opening sentence is boilerplate ('calls the Actor ... and retrieves its output results'), but the embedded Actor description supplies a concrete verb+resource: tracking product/URL/Smartstore rank in Naver Shopping for Korean keywords, including the data returned (organic rank 1–35, ad slot, price, reviews). That is enough to distinguish it from the other Naver siblings (ai-briefing-monitor, blog-brand-monitor), though the differentiation comes from domain wording rather than an explicit contrast.

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

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

Usage is implied rather than stated: 'a Naver Shopping scraper built for scheduled rank monitoring' and the rankHistoryStore note 'Run on a schedule to track movement' tell the agent the intended scenario. There is no explicit when-not-to-use and no named alternative among the siblings (e.g. when to poll via get-actor-run instead of calling this tool directly), so guidance stays at the implied level.

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