Website Change Monitor: Page Diffs, Price & Keyword Alerts

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

Annotations already declare readOnly/openWorld/non-idempotent, but the description adds substantial context beyond them: the first-run-only-saves-baselines state machine, that the webhook posts outside the Apify run and only when something changed, that unreachable pages are free while unchanged pages are still billed at $0.0015/page, the run_max_charge_usd cap, and the 5-15 s / 300 s timeout envelope. It even reconciles with annotations by asserting 'read-only' while disclosing the persistent key-value snapshot store.

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 critical framing (what it is, what it is not, when to use) is front-loaded in the first three sentences, and the return-field list and billing paragraphs are placed after the decision-relevant content. It is long and some parameter prose duplicates the schema verbatim, but for a 13-parameter stateful tool with non-obvious cost semantics the density is largely earned.

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

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

Despite having no output schema, the description enumerates the returned fields (agentSummary, status, addedLines, priceChanges, keywordsAppeared, titleBefore/After, previousCheckAt) and the envelope shape {actor, count, items}. It also covers cost model, spend cap, timeout remediation, and webhook side effects, leaving no material gap for calling the tool correctly.

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

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

Schema coverage is 100%, so the schema baseline is 3; the description goes further by explaining cross-parameter interactions the schema only states locally, notably that the first run per monitorName only saves a baseline and must be reused for later runs, and that run_max_items fills maxPages when left unset and therefore also bounds billing. It restates some parameters (webhookUrl, onlyReportChanges, ignorePatterns) that the schema already documents well, so it stops short of a 5.

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

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

States a specific verb and resource ('Check a watch list of web pages against snapshots saved by your previous run') and enumerates the concrete outputs: added/removed text, change percent, price changes, keyword alerts. It explicitly names the two sibling tools it is not (ai_search_seo_audit, hidden_ai_instructions_scanner) and characterizes itself as 'stateful diffing over time', so an agent can discriminate without opening any 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 explicit when-to-use ('track competitor pricing, terms, product or careers pages on a schedule') and explicit when-not ('Do not use for a one-off page read or audit (use ai_search_seo_audit), or for pages behind a login'), naming the alternative to select instead. Exclusions cover both the wrong task shape and an unsupported page class.

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