pbi_apply_plan

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

Beyond the destructiveHint annotation, the description adds critical behavioral details: it verifies project state before applying, rejects changes if state differs, requires confirm=true, and explains the historical default change. This adds significant value beyond 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 description is moderately long but well-structured: it opens with the main purpose, then safety checks, then param clarification, then confirmation requirement with rationale. Every sentence adds value without redundancy.

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 output schema exists and annotations cover destructive nature, the description sufficiently covers the safety mechanism, the optional parameter, and the confirmation gate. It could elaborate on error scenarios beyond plan_operation_mismatch, but overall it's complete for its complexity.

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. It explains expected_operation and confirm explicitly, but plan_token and request_id are not described. plan_token is inferable as the plan identifier, but request_id remains undocumented. Partial compensation.

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 applies a plan calculated with pbi_plan_change or a dry_run. It distinguishes itself from sibling tools by specifying the source of the plan and the additional verification step, making its purpose distinct.

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 implies usage after plan generation and emphasizes the need for confirm=true. It does not explicitly name alternatives, but the context (plan_change vs apply) is clear. The expected_operation parameter is explained as a safety mechanism.

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