agent_apply

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the mutation risk is known. The description adds two real behavioral facts beyond that: the apply is single-shot ("once") and is gated by an operator startup policy that may refuse it. However, it never says what that policy is, what a refusal looks like, whether the plan is consumed on failure, or whether the change is undoable.

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?

A single front-loaded clause pair with no filler; the verb and the scope arrive immediately. The only weakness is that "operator startup policy" is unexplained jargon occupying a third of the text's information budget.

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?

This is a destructive, non-read-only operation with no output schema and an undocumented sole parameter, so the description bears the full burden. It leaves unaddressed what apply returns, whether the plan is consumed, what happens on a second call with the same id, and how to recover — all material for a destructive tool.

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% and there is one required parameter, so the description must carry the meaning — and it does partially, making clear that plan_id is an opaque handle to a previously returned preview rather than a user-chosen identifier. It adds nothing about handle lifetime, invalidation after use, or format, so an agent still cannot predict failure modes from the parameter.

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?

States a specific verb ("Apply") on a specific resource ("a previously returned preview"), which implicitly ties it to the agent_*_preview siblings that produce such previews. An agent can tell this is the commit step rather than a preview, though the description never names the producer tool explicitly and "preview" remains an abstract object.

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?

"once" and "previously returned" imply the prerequisite (a preview must exist first) and hint at single-use semantics, but the description never states when to prefer this over re-running a preview or over applying edits directly via edit_* tools. No explicit exclusions or alternative routing is given.

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