Start a change monitor (scheduled)

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.