Check watches

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

Beyond the sparse annotations, the description reveals critical behavioral traits: it 'advances each watch's last-notified marker' (a side effect), a first pull returns the entire standing set rather than an increment, and results can be truncated to 100 with the remainder not re-reported later. These disclosures go far beyond the annotations and prevent misinterpretation.

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 front-loaded with the core action, then adds three distinct behavioral nuances (side effect, first-pull semantics, truncation) in separate paragraphs. Every sentence earns its place, with no filler 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?

Even without an output schema, the description specifies the key result fields (is_first_pull, total_matching, truncated) and explains the edge cases that matter for correct interpretation. It also covers when to call the tool and what the side effect is, making it self-sufficient for an agent.

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?

With 0% schema coverage, the description carries the parameter explanation. It clarifies that fingerprint is tied to a last-check state and that results are per watch, adding meaning the bare string schema lacks. However, it leaves some ambiguity about what the fingerprint identifies (a user, device, or watch set), so it is not fully explicit.

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 opens with a specific verb+resource: 'Pull matches that are new since this fingerprint's last check.' This clearly identifies the tool as a polling operation for watch results and distinguishes it from sibling tools like search_jobs (search) and watch_intent (watch creation), even without naming them explicitly.

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?

It gives a strong when-to-use directive: 'call this at the start of a session' and explains the push/pull rationale. However, it does not explicitly contrast with alternatives (e.g., when to use search_jobs instead), so it stops short of the full when-not-to-use guidance needed for a 5.

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