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

The 'WRITE:' prefix and 'PUT /tasks/{id}' disclose the mutation nature and endpoint, and the partial-update behavior is stated. Annotations already flag destructiveHint, so the description needn't repeat safety; it adds useful context about which fields are left untouched.

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?

Front-loads the 'WRITE:' intent and operation, packs examples and partial-update semantics into two sentences, ends with the endpoint. Efficient with minimal waste.

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?

Covers the operation, scope, partial-update behavior, examples, and endpoint. Without an output schema, it omits return details, but for an update tool with full annotation coverage this is largely complete.

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%, so the baseline is 3, but the description adds meaning by grouping fields by task type (to-do vs appointment vs note) and giving examples like marking done or rescheduling, which contextually enriches otherwise sparse schema descriptions.

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?

States a specific verb (change/update) and resource (note, to-do, appointment), and gives concrete examples (mark done, move due date, reschedule). Easily distinguished from siblings like propstack_create_task and propstack_get_task.

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?

Implies usage for modifying existing tasks, and 'Fields not given stay as they are' clarifies partial-update semantics, but never explicitly says when to use this vs. create_task or update_contact.

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