apply_plan

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the tool executes a plan and includes automatic rollback on failure, which is a key behavioral trait. It also explains the dry_run behavior (no side effects, uses a dry-run executor) and notes that confirm_each_step is not enforced. However, it doesn't disclose potential side effects beyond that, such as whether the plan is idempotent or what happens to partially executed steps beyond rollback. The behavior is partially transparent but not fully.

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 concise and structured with clear sections for summary, args, and returns. The summary is front-loaded, which helps agents quickly grasp the purpose. The args section is efficient, using bullet points for clarity. The only minor issue is that the returns section is brief, but that's acceptable given an output schema exists. Overall, every sentence adds value without fluff.

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 the tool's complexity (it executes plans with rollback) and the existence of an output schema, the description covers essential details: purpose, parameters, and behavior. The description also clarifies the status of confirm_each_step, which is important to avoid confusion. Since an output schema is present, the lack of detailed return information is acceptable. An agent has enough information to invoke 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 description coverage is 0%, so the description must fully explain the parameters. It does so comprehensively: plan_id is explained as the ID of a plan created by plan_change; dry_run is described with its behavior (no side effects, dry-run executor used); confirm_each_step is explained as reserved for v2 and not enforced. This goes beyond the schema's bare definitions and gives agents the necessary context to use the parameters correctly.

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's purpose: executing a plan with automatic rollback on failure. It identifies the specific resource (plan) and the action (execute), and mentions plan_id as the identifier of a plan created by plan_change. This distinguishes it from siblings like plan_change (which creates plans) and pre_deploy_check (which likely validates before execution).

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 implies usage by stating the plan_id must reference a plan previously created by plan_change, which gives context on when to use this tool. However, it doesn't explicitly state when not to use it or mention alternatives. There is no guidance on when to use dry_run vs. normal execution, though the parameter description hints at it. A clear exclusion or alternative mention would improve this.

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