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

Annotations only mark this as a non-read-only, non-destructive local write; the description adds much more: name grammar, that the batch takes the next sequential number and queue position, that works start planned in order, that the result carries batch-scoped references, and the side effect of completing a planning step (and an open Evaluate-the-idea step) with edgeId avoiding a separate resume_workflow call. It also discloses that rule checks are performed by TypeSafe, a separate provider receiving record, rule text and project context — a genuinely useful data-flow disclosure.

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-loaded with purpose and the sibling contrast, and nearly every sentence carries information. However it is a single undifferentiated block in which the runId and edgeId notes are interleaved with the create_work comparison, and the TypeSafe paragraph arrives without a clear lead-in.

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?

With no output schema, the description compensates by describing the result (batch-scoped work references like `4-1`, sequential numbering), and it covers the workflow-run interplay and the external rules provider. Gaps remain around failure behavior — duplicate names, partial creation, and what requestId retry actually returns — though requestId is documented in the schema.

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 real meaning for two parameters: runId ('When several workflow runs wait for a Batch, pass runId to plan it for that run') and edgeId ('can name the Batch stage route so no separate resume_workflow call is needed'). It also conveys that works ordering is meaningful. metrics and requestId semantics are left entirely to 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 and resource with scope: 'Create a planned batch and its planned works in one call.' It explicitly differentiates from the nearest sibling by noting 'create_work adds a Work to an existing Batch,' so an agent can route between them without reading schemas.

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?

Gives clear positive guidance ('This is the normal way to plan a batch once its scope is agreed') and names the alternative create_work plus the runId condition for workflow runs. It stops short of explicit when-not-to-use cases, e.g. it never says to use update_batch/revert_batch instead of re-planning an existing batch.

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