processing_apply_plan

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates state. The description adds the crucial 'verified' and 'task-scoped' context, and the schema's session_fingerprint parameter description elaborates on the concurrency-guard/refusal behavior after bridge reload. The description itself is brief, but combined with the rich parameter descriptions (which are part of the schema, not annotations), the behavioral profile is well covered.

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 a single, compact sentence that front-loads the core purpose (apply a plan) and its key constraint (task-scoped, verified, one Production Run). It's appropriately sized for the tool's complexity. No waste, though it could have added a sentence on safety consequences of the destructive action.

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 (3 required params, rich nested schema, output schema present, annotations covering destructive behavior), the description plus schema documentation fully covers what an agent needs: what to pass (plan from processing_plan, valid fingerprint, authorization flag), what happens semantically (verified run), and what safety class it falls into (destructive, not idempotent). The output schema exists, so return values need no description.

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 100%, so the baseline is 3. The description adds value by explaining that the plan must come from processing_plan (in the plan parameter description) and by detailing the session_fingerprint's role as a concurrency guard that 'refuses after bridge reload or a reported project load.' It also clarifies that authorized_to_modify reflects explicit user authorization. This is meaningful semantic context beyond the raw field definitions.

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 states a specific verb ('Apply') and resource ('a semantic plan through one task-scoped verified Production Run'). It clearly identifies the tool's function and differentiates it from sibling tools like processing_plan (which creates the plan) and mix_apply_plan (a different apply-plan tool). The annotation title confirms the purpose without replacing it.

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 implicitly establishes usage: you must already have a plan (from processing_plan, as referenced in the schema's plan parameter description). The 'verified Production Run' phrase signals this is the execution step after planning. It doesn't explicitly name alternatives or exclusions, but the workflow context is clear enough for an agent to select it over planning/read-only tools.

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