watch_add

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

No annotations are provided, so the description carries the full burden. It does disclose key behavioral traits: first snapshot is git-committed to the watch store, fires only when visible text changes, link-token churn never false-fires, and name defaults to a URL slug. However, it doesn't explain what the return value is, how to stop/remove a watch, or any limits on concurrent watches. Reasonable transparency but gaps remain for a tool with zero annotations and no output 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?

The description is economically written in a single concise paragraph, front-loads the core purpose, and every clause adds meaningful information. Minor inefficiency in slightly awkward phrasing ('let later watch_scan calls fire when...'), but no wasted words or redundancy.

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?

The tool has 3 parameters with 0% schema coverage and no annotations or output schema, so the description must compensate heavily. It explains the watch mechanism well and distinguishes from watch_scan, but leaves 'private' semantics unexplained, doesn't describe what the tool returns, and doesn't address how the watch integrates with watch_list/watch_diff/watch_remove. Adequate for basic use but incomplete for a tool that creates persistent state.

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 0%, meaning all 3 parameters (url, name, private) are undocumented in the schema itself and there are no parameter descriptions. The description mentions 'Name defaults to a slug of the URL' (clarifying the 'name' parameter's default behavior), which adds some value, but 'url' and especially 'private' are completely unexplained — the semantics of the private flag are entirely opaque.

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 specific verb+resource ('Start watching a URL for real content change'), explains the core action (takes snapshot now, fires later on visible text change only), and distinguishes from the sibling watch_scan tool by noting when scan fires. Clear and precise.

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 explains the mechanism (initial snapshot, subsequent fires on visible text change) which implies when this should be used (to monitor content change). However, it doesn't explicitly state when NOT to use it or name alternative tools, though watch_scan is implicitly contrasted. Decent implied guidance but no explicit exclusions or named alternatives for differing use cases.

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