update_plan

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

With no annotations provided, the description carries the behavioral disclosure burden. It explains the merge-vs-replace behavior is in the schema (the 'replace' parameter), but the description itself doesn't disclose mutation behavior, authorization needs, or consequences. The description is functional but doesn't add rich behavioral context beyond what the schema provides, such as whether plans are idempotent or what happens on conflict.

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?

Three sentences, front-loaded with purpose, then guidance, then storage details. Each sentence earns its place. It's appropriately concise for a moderately complex tool with 8 parameters. Not overly verbose, no wasted words.

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?

Given 8 parameters at 100% schema coverage, no output schema, and moderate complexity (plans with multiple field-based construction options), the description adequately covers the tool's purpose and usage. It could be more thorough about the merge/append semantics and how fields combine into a plan file, but overall it provides sufficient context for an agent to use the tool correctly.

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 schema documents all 8 parameters fully. The description adds some value by indicating 'content' replaces the entire file (matching schema) and 'description' is used when building from fields. However, the description doesn't clarify the relationship between 'content' and the other field-based params or how merge/append works, which is a nuanced behavior the schema doesn't fully explain.

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 clearly states the tool documents/updates feature plans, what to include (files, design decisions, status), and where plans are stored (.wisdom/plans/). It uses a clear verb ('update'/'document') with a specific resource (feature plans). It doesn't explicitly differentiate from siblings, but the resource is distinctive enough given the sibling list contains unrelated tools like prune_context and inject_context.

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?

The description gives clear context on when to use: 'when you complete or change direction on a feature' and 'Update existing plans when you complete or change direction.' It explains the storage location and cross-referencing. However, it doesn't explicitly name alternative tools or say when NOT to use this tool, though the siblings are largely unrelated.

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