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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation. The description adds genuinely useful partial-update semantics ('Only the fields you pass are changed'), which the annotations do not convey. It says nothing about the unusual approval_id parameter, permission requirements, or what happens to fields left out, so it adds only one meaningful behavioral fact.

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 the affected fields front-loaded and the partial-update rule second. Nothing is wasted, though the 'When a task changed' opener is slightly awkward and reads more like an event description than an instruction.

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?

An output schema exists, so return values need no explanation, and the field list is covered. The notable gap is approval_id, whose schema text hints that execution may require a human-approved request — a workflow constraint an agent should know before invoking, and it is absent from the description.

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 100%, so the schema already documents all six parameters and the baseline is 3. The description reinforces the editable field set in prose but adds no format or constraint detail beyond the schema, and omits task_id and approval_id entirely. Adequate but not additive.

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 names the resource (task) and the specific fields it can change (title, description, completion state, linked contact), so an agent can tell it apart from generic updaters. It is phrased as a trigger event ('When a task changed') rather than an explicit verb, but the intent is unambiguous. It does not explicitly disambiguate from the sibling tasks.complete, which is a small clarity gap.

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?

Usage is implied by the scenario framing ('when a task changed'), giving an agent a rough sense of when to reach for it. However there are no explicit when-not conditions or named alternatives, and it never addresses the overlap with tasks.complete despite claiming it can change completion state. That silent overlap is the main guidance gap.

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