archive_plan

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

With no annotations, the description carries the full burden and does so thoroughly: it names the required permission (can_archive_plan), lists the exact tools that will reject the plan with the structured plan_archived error, discloses idempotency and irreversibility, confirms data retention (tasks, events, board cards intact), and notes the Slack side effect.

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 description is dense but front-loaded, leading with purpose and permission before enumerating rejected tools, lifecycle behavior, and the Slack/return details. Almost every sentence adds distinct value, though the volume could be trimmed slightly without losing 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 mutation tool with no annotations and no output schema, the description fully covers prerequisites, side effects, error behavior, and even return values (plan id, new status, resolved outcome, already_archived). Nothing an agent needs to invoke it correctly is missing.

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 0%, so the description must compensate. It explains Outcome ('Completed' default or 'Canceled', suffixing the audit milestone title and appearing on Slack), Reason (shown on the Slack notice), and PlanId implicitly as the target plan. Only as_agent is left undocumented, so it substantially covers three of four parameters.

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 gives a precise verb+resource ('Archive (disable) a plan') plus the immediate effect ('so it stops accepting work'). It clearly distinguishes this from siblings like activate_plan, create_task, and cancel_audit by naming the exact tools and behaviors an archived plan blocks.

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 when to use it ('retire a finished or abandoned plan') and explains the downstream consequence (the next orchestrator bootstrap creates a fresh plan, enabling a new audit/development pass). It also clarifies it is one-way and idempotent, removing ambiguity about repeated invocation.

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