watch_scan

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

With no annotations provided, the description carries the full burden and does well. It discloses a critical behavioral trait: changes are detected on visible text only, meaning a 'changed' reading signifies a reader would agree the page changed. It also clarifies that 'snapshot committed' on changed and reports 'why' on error. This is meaningful behavioral context beyond what structured fields would provide.

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 compact (two sentences) and front-loaded with the core action and the three status outcomes. Every sentence earns its place — the visible-text detection detail and empty-names behavior are both useful. Slightly dense with the parenthetical explanations but no wasted words.

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 a single-parameter tool with no output schema, the description covers the action, the result statuses, the return-field example (diff_sample), the default behavior, and the critical scoping constraint (visible text only). This is fairly complete for the tool's simplicity. It could have noted the need for prior watch_add setup, but the sibling structures make that inferable.

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 0% and there is only 1 parameter (names, an array with no item type specified). The description compensates somewhat by noting 'Empty names scans everything,' which clarifies the default/empty behavior of the names parameter. However, it doesn't explain what the array items should be (watch identifiers? names?), leaving ambiguity about how to populate the parameter.

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 clearly states the tool re-fetches watches and reports one reading each (ok/changed/error), distinguishing its monitoring/scanning purpose from sibling tools like watch_list (lists watches) and watch_diff (shows diffs). It's specific about the verb and resource ('re-fetch watches') and the three possible outcomes. However, it doesn't explicitly distinguish it from watch_diff, which is a close sibling.

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 states 'Empty names scans everything,' giving useful default behavior, and explains the semantics of each result status. However, it doesn't explicitly say when to use this vs watch_diff or watch_list, nor does it mention any prerequisites (e.g., must have watches added first via watch_add). Usage context is implied but not explicitly contrasted with alternatives.

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