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

Annotations already indicate this is not read-only, is idempotent, and is non-destructive. The description adds useful behavioral context beyond those hints by specifying that weekly re-reads cease while the record persists, and that the operation can be reversed via the resume sibling.

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?

Two compact sentences with no filler. The core action is front-loaded, the behavioral consequence is stated immediately, and the resume alternative is given in a single short clause. Every sentence earns its place.

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 simple pause action with two required IDs, the description covers the essential effect and reversal path. The absence of an output schema makes return-value details missing, but that is a minor gap for this kind of mutation; annotations already communicate idempotency and non-destructiveness.

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%, and the description does not compensate by explaining workspaceId or watchId. The parameter names are fairly self-explanatory, but the description offers no guidance on what these IDs refer to or how they relate to the paused watch, so it fails to add meaning beyond the bare schema.

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 starts with a specific verb and resource: 'Pause a company employee watch.' It clearly states the operational effect ('weekly re-reads stop') and the key non-destructive detail ('the record stays'), distinguishing it from removal tools like campaignstack_remove_company_employee_watch.

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 use the tool: when you want to stop weekly re-reads but retain the watch record. It also names the exact sibling tool for reversing the action, campaignstack_resume_company_employee_watch, providing an explicit alternative.

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