watch

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

Rich disclosure beyond annotations: persistence across restarts, fire-and-forget triggering on sibling tool calls, SSRF rejection at registration, a 60-second floor for target-site rate limits, and best-effort webhook delivery with no retry/queue/backoff. One nuance conflicts with annotations — the description says `create` is idempotent while `idempotentHint=false` — though that hint remains defensible for `check`/`delete`, so this is a clarification rather than a hard contradiction.

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 single most important fact ('LAZY EXECUTION — NOT CRON') before any parameter detail, and the bulleted parameter block is scannable. A few lines merely restate the schema's action enum and create-only flags, which is the only mild redundancy in an otherwise dense, purposeful 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?

Given seven parameters, six actions, no output schema, and an unusual lazy-execution model, the description covers lifecycle, trigger conditions, failure modes, idempotency, and the one return field that matters (`staleness_seconds`). An agent could invoke every action correctly from this text alone.

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 already 100%, so the baseline would be 3; the description goes well past it by adding constraints (public http/https only, loopback/RFC 1918/link-local rejected, interval min 60), the forward-compatibility caveat that `selector` is persisted but diffs are currently full-page, and the meaning of `staleness_seconds` (negative = not due, positive = overdue by N).

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?

Opens with a specific verb+resource+outcome: 'Schedule lazy re-checks of a URL and surface diffs on change,' which immediately separates it from the one-shot `fetch`, `crawl`, and `diff` siblings. It does not, however, explicitly name any sibling and contrast itself with `diff` (which presumably does a one-shot comparison), leaving a small inference gap.

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 states when checks fire ('ONLY when: 1... 2...'), what does NOT happen ('no background daemon', 'not cron'), and pairs `list` with `check` to force immediate execution. The action enumerations are each given a context of use rather than left to inference.

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