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

With no annotations, the description carries the full load and does well: it discloses the data source (stored daily snapshots), performance expectations (returns in seconds, no crawling), and a material data caveat (collection began 2026-11-05, first month is short). It stops short of describing result size, pagination, or behavior when all filters are omitted.

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

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

Three tight sentences, front-loaded with the returned metrics and followed by the freshness/performance caveats. Minor noise: the shop list is repeated from the schema, and it names only Fujiya, Sanpou and Naniwa while `sources` also includes hardoff.

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

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

For an 8-parameter, no-output-schema, no-annotation tool, the description covers the return shape and data freshness but leaves the two price-bound parameters unexplained and omits hardoff from the snapshot coverage. The unenforced "needs keywords, brands or models" requirement is a notable unresolved ambiguity.

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 75%, so the baseline is 3. The description adds the collection start date, which gives the `days` parameter real meaning, but it ignores minPriceJpy/maxPriceJpy entirely, and "Needs keywords, brands or models" conflicts with a schema declaring zero required parameters - an agent could reasonably expect a validation error that will not occur.

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 resource and output shape: "Daily min / median / max / count per model, by shop and condition grade." The phrase "from stored daily snapshots ... No crawling — returns in seconds" implicitly separates it from a live-crawl sibling like search_listings, but neither price_stats nor search_listings is named, so sibling routing is left partly to inference.

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?

"Needs keywords, brands or models" gives a precondition for use, which is real guidance. However, there is no explicit when-not, no statement of how this differs from price_stats (which supplies the model keys), and no guidance on what happens if no filter is supplied.

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 no annotations, the description carries the burden and does reasonably well: it discloses latency (~1–4 min), that only in-stock listings are counted, and exactly what aggregates are returned. It does not explicitly state read-only behavior or rate limits, but the latency warning is the operationally important trait for a long-running read.

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?

A single dense sentence, front-loaded with the core purpose and return contents, ending with the actionable performance hint. The parenthetical currency and timing details earn their space, though the sentence is long enough to be slightly harder to scan.

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

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

With no output schema and no annotations, the description effectively substitutes for one by enumerating the returned statistics and their groupings. The main residual gap is the two undocumented price-bound filters, plus no explicit statement of read-only semantics for a 7-parameter tool.

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

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

Schema coverage is 71%, so the baseline is 3, and the description adds real value on top: it links keywords to reduced runtime and maps the shop/condition breakdown outputs back to the sources and grades filters. minPriceJpy and maxPriceJpy remain undocumented in both schema and description, which keeps it below 5.

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

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

The description names the resource precisely (per-model price summary of in-stock listings) and enumerates the computed statistics (count, min/median/max in JPY and USD, per-shop and per-grade breakdowns, cheapest listing). That distinguishes it from search_listings and price_history by implication, though it never names those siblings explicitly.

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: an agent can infer this is the tool for aggregate current pricing rather than listing retrieval or historical trends. The only explicit guidance is the performance tip to use keywords to stay fast, with no when-not-to-use conditions or named alternatives.

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

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

With no annotations, the description carries the full burden and usefully discloses source coverage, returned fields, and a 15–60 s latency expectation. It does not clarify read-only behavior, authentication needs, failure modes, or whether results are cached/live beyond the word 'current'.

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 three compact sentences: purpose first, returned fields second, latency last. Every sentence adds relevant information without repetition or filler.

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

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

For an eight-parameter search tool with no output schema and no annotations, the description supplies the key return shape, source scope, and expected latency. It remains slightly incomplete on price-filter semantics, sorting behavior, and operational caveats, but is sufficient for an agent to understand and call the tool.

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

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

Schema description coverage is 75%, so the schema already documents most parameters, including brands, grades, sources, keywords, maxItems, and includeSoldOut. The description adds little parameter-specific meaning beyond mentioning source shops and normalized condition grades, and the min/max price filters are left without extra explanation.

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 specific verb and resource: searching current used camera/lens listings at named Japanese shops. It clearly distinguishes the tool from price-oriented siblings by focusing on live listings, though it does not explicitly reference the sibling tools.

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 context implies this is the tool for finding current listings rather than price statistics, price history, or monitoring. However, it provides no explicit when-to-use guidance, exclusions, or routing against the sibling tools.

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

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

With no annotations supplied, the description carries the full burden and does it well: it discloses that resources are created in the user's own Apify account, that runs are recurring and billable against their credit, that a baseline run happens immediately, and that later runs only emit deltas which may be POSTed to a webhook. This is exactly the side-effect and cost information an agent needs before invoking a mutating, scheduled 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?

Two sentences, front-loaded with what happens and followed by the risk warning; nothing is redundant. The cost/confirmation warning is placed at the end where it functions as a final gate before invocation.

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

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

For an 11-parameter, annotation-free tool with no output schema, the description covers the mutation and cost side well but says nothing about what is returned (task ID, schedule ID, run ID) or how a monitor is later stopped or modified. Those omissions matter because nothing else in the definition supplies them.

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 73% and the schema already documents cron defaults, grade ordering, source semantics, and alertEvents defaults, so the description adds little parameter-level detail beyond restating the event types and the default hourly cadence. It does not explain how filters like brands/keywords/price bounds interact with the change detection, which would have been genuine added 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?

States a concrete verb chain and resources: creates a saved Task in monitor mode, a Schedule, and starts a baseline run. It also clarifies that subsequent runs emit only change events, which cleanly separates this write/setup tool from the read-only siblings search_listings, price_stats, and price_history.

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 operating context (long-running monitoring with change-only output) and an explicit precondition -- confirm with the user first because it consumes Apify credit. It never explicitly contrasts itself with the sibling query tools (e.g. 'use search_listings for a one-off check'), so the alternative selection is implied rather than stated.

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