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

Annotations already mark the operation as non-read-only and destructive, and the description adds meaningful behavioral detail: it 'Resets the deadline and delivery state, potentially suppressing an overdue alert or rearming delivery.' This explains the real side effects beyond just 'reset,' which is helpful context for an agent deciding whether calling it could change alerting behavior.

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 and front-loaded, starting with the memorable 'Still alive.' followed immediately by the core action. Every sentence earns its place: one defines the action, one provides usage frequency, and one explains the behavioral consequences.

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 two straightforward parameters, one required, and a clear keepalive use case, the description covers the action, cadence, and side effects. It does not describe a return value, but there is no output schema and the important operational behavior is already disclosed. The only minor gap is that it does not explicitly explain what happens if the interval is missed, though 'suppressing an overdue alert' implies it.

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?

The schema covers both parameters fully: 'name' is described as the watchdog name with length constraints, and 'vigil_key' is documented as a deprecated credential with clear guidance to omit it when using the Authorization header. The description adds no parameter-specific meaning, so the schema-description coverage baseline of 3 applies.

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 uses a specific verb and resource: 'Reset a watchdog's timer.' The phrase 'Still alive.' and the repeated reset semantics make the tool's purpose unmistakable and distinguish it from siblings like vigil_set_watchdog or vigil_delete_watchdog, which create or remove watchdogs rather than refresh them.

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 gives clear context for when to call the tool: 'Call this at least once per interval.' It also hints at the consequence of failing to call it by mentioning 'suppressing an overdue alert.' It does not explicitly name alternatives or state when not to use it, but the intended keepalive pattern is clear.

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