patch_plan

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

With zero annotations, the description carries the full burden and excels: it discloses the atomicity guarantee (acquires the same _plan_lock as the scheduler and dispatch_story), the concurrency race it prevents, and the fail-closed validation that rejects unknown fields before the lock is taken so nothing invalid reaches disk. These are exactly the behavioral traits an agent needs to trust a mutation tool, all beyond what any structured field would reveal.

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?

The purpose is front-loaded in the first sentence, and each subsequent sentence earns its place: the race explanation justifies why the tool exists, the lock detail establishes the atomicity guarantee, and the fail-closed note covers safety. It runs to four sentences, slightly longer than minimal, but none are filler, so it reads as dense and purposeful rather than verbose.

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?

The presence of an output schema covers return values, and the description addresses the essential concerns for a patch operation: what can be edited, why it's safe, and the validation boundary. Minor gaps remain - the precise shape of role_config and exact error behavior on rejection aren't detailed - but for a two-parameter mutation tool the description covers the high-risk aspects comprehensively.

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%, so the description must compensate for both parameters. It clarifies that fields may only contain role_config and that setting any other top-level field is rejected fail-closed, which maps directly to the 'fields' object parameter. plan_name is implied by context as the plan identifier. It doesn't spell out plan_name's role or role_config's internal shape, but it adds substantial meaning the empty schema lacks, earning a 4.

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 (edit) and resource (plan manifest top-level fields), and immediately narrows scope to 'currently only role_config'. This clearly distinguishes it from sibling patch_story (stories vs plan manifests) and save_plan/ingest_plan (whole-plan creation/import vs targeted field edit). An agent can select it correctly without ambiguity.

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 frames the tool as the correct alternative to hand-editing the manifest JSON, warning of the read-modify-write race with the scheduler's 60s advance_all_plans tick. It clearly states only role_config may be set and every other top-level field is rejected, defining what not to use it for. It stops short of naming specific sibling tools as alternatives for other operations, so it's a 4 rather than a 5.

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