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

Annotations already declare destructiveHint/readOnlyHint, but the description adds genuinely new behavioral facts: partial-update semantics ('Only supplied fields change'), that batchId is an intentional relocation, and that title/description/labels/size/Batch edits are validated against the Batch's ruleset with a failed Must rule refusing the write. That is substantial disclosure of mutation behavior and failure modes beyond the 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?

Purpose and partial-update rule are front-loaded, and each sentence carries content. The final ruleset sentence is dense and syntactically convoluted ('the rulesets on the connection the run entered Batch on'), which slightly hurts readability but not substance.

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 7-parameter mutation tool with no output schema and no nested objects, the description covers purpose, update granularity, parameter intent, the workflow-run validation gate, and the failure outcome. It is nearly complete, with only minor gaps such as behavior of non-Must rule failures and permission/auth requirements.

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 intent beyond the schema's terse field docs: batchId 'deliberately moves a planned Work' and status is constrained to a queue-return operation. It does not clarify the enum values for size or label semantics beyond the 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?

States a specific verb+resource ("Edit a Work's planning details") and immediately carves out scope against the lifecycle siblings by declaring that a Work starts only through begin_work and finishes only through finish_work. An agent can distinguish this from create_work, delete_work, begin_work and finish_work without opening any schema.

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?

Explicitly names the alternative tools (begin_work, finish_work) and the exact condition that selects them, and constrains the status parameter to the single legitimate value 'planned, to send a started Work back to the queue'. This is clear when-to-use and when-not-to-use guidance rather than implied context.

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