stop_watch

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

Annotations only provide negative hints, so the description carries the disclosure burden. It adds meaningful behavioral detail: the watch is scoped to this conversation, stopping it prevents further notifications, cross-session watch ids are not found and never stopped, and results carry an attribution line. No contradiction with annotations.

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 first sentence front-loads the core action, and the following sentences each earn their place by covering usage triggers, exclusions, and edge cases. It is dense but well-organized; the only slightly cryptic part is the closing line about the attribution line.

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 narrow stop-watch action, the description covers the key aspects: what the watch is, when to stop it, how to resolve an id, and what does not work. With no output schema, the mention of 'Results carry their attribution line' is vague, but it is a minor gap for this simple tool.

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 100% and the parameter descriptions are already thorough, giving a baseline of 3. The description adds useful resolution guidance: when the user names a subject instead of an id, the agent should take the id from viafrei://watches. This goes beyond the schema's field-level documentation.

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 and resource: 'Ends a watch this conversation opened with watch_situation'. It clearly distinguishes this from sibling tools like watch_situation and check_road_status, so an agent knows exactly what the tool does.

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 explicitly states when to use the tool ('when the person no longer needs to be told'), gives concrete examples, and lists what not to use it for with named alternatives: check_road_status for lookups and viafrei://watches for listing. It also excludes cancelling anything outside this chat.

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