Stage Code Action

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

Beyond annotations, the description discloses that staging does not write source files, successful staging consumes the action reference, and the returned snapshot must be used before selecting another action. It also states that prepared Fix All staging must match the exact prepared change set and document limit. It does not cover failure modes or authorization requirements, but the annotations already carry the safety profile.

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 action is front-loaded in the first sentence, followed by transactional sequencing and constraints. Despite covering a complex workflow, every sentence provides operational guidance and there is no obvious filler.

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 annotations, a nested input schema, and an output schema, the description is complete enough for correct invocation. It explains the transaction lifecycle context, actionId sourcing, snapshot matching, and next-step alternatives without needing to restate return-value details.

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 100%, so the parameters are already well documented. The description adds useful meaning by explaining that actionId comes from list-code-actions or prepare-fix-all and that expectedSnapshot must match the state used to construct the request, including the prepared change set and document limit for Fix All.

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 specific verb and resource: it revalidates and stages a selected Code Fix, refactoring, or prepared Fix All operation in the active transaction. It clearly distinguishes this staging step from discovery via list-code-actions, preparation via prepare-fix-all, and later transaction-preview/commit/rollback actions.

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 explicitly says to start the transaction before discovery or preparation, where to get actionId, and how to use prepare-fix-all output with the matching expectedSnapshot. It also names the correct inspection and completion alternatives: transaction-preview or transaction-review, then transaction-commit or transaction-rollback.

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