archive_plan

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

Annotations only flag destructive/idempotent; the description goes far beyond by naming the required permission (can_archive_plan), enumerating exactly which tools reject an archived plan and with which structured error (plan_archived), stating irreversibility, and confirming tasks/events/board cards survive for forensics. It also discloses the side effect of posting a plan.archived Slack notice and the returned fields, none of which is in 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?

The core action and permission requirement are front-loaded, and nearly every sentence adds operational value (blocked tools, error code, idempotency, side effects). It is a dense single block though; the return-value and outcome detail could be split or trimmed without loss.

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 destructive, permission-gated mutation the description covers effects, reversibility, idempotency, side effects, and return values (no output schema exists, so this matters). The only real gap is the undocumented `as_agent` parameter, which an agent may need for correct invocation.

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?

With 0% schema coverage the description must carry parameter meaning, and it does for Outcome ('Completed' default or 'Canceled', suffixing the audit milestone title and appearing on Slack) and Reason (shown on the Slack notice); PlanId is self-evident. However, the fourth parameter `as_agent` is never explained, leaving one of four parameters undocumented anywhere.

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 opens with a specific verb and resource — 'Archive (disable) a plan so it stops accepting work' — and immediately clarifies the semantic effect (disable, not delete). It is clearly distinguishable from siblings like activate_plan and create_plan, which it mentions by name in the effect list.

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?

It states exactly when to reach for this tool ('retire a finished or abandoned plan') and explains the downstream lifecycle consequence: the next orchestrator bootstrap finds no active plan and creates a fresh one, which is how a new pass is started on demand. It also gives the key when-not signal implicitly and explicitly via the one-way, no-un-archive constraint, so an agent knows there is no undo path.

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