do_promote

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

With no annotations provided, the description carries the full burden and does disclose meaningful behavior: this is a state-changing move with per-phase prerequisites, a confirm gate, and a human-in-the-loop recommendation for serve. It says nothing about reversibility, permissions, failure behavior, or what happens to the point's current state, which matters for an unannotated mutation tool.

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 signature is front-loaded, which is good, but the remainder is a single overloaded run-on of parenthetical conditions and internal cross-references that an unfamiliar agent cannot resolve. Nothing looks purely redundant, yet the density and section-number shorthand hurt scannability.

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?

An output schema exists, so return values need not be covered, and the description does address the biggest gap by enumerating payload fields despite a fully opaque schema. Still, the plan_phase and workflow/downgrade variants are gestured at via §15.6/§15.8 without explanation, and no annotation coverage exists to backstop the mutation semantics.

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 the schema exposes only an untyped 'payload' object with additionalProperties, so the description is the sole source of parameter meaning. It compensates well by naming the required fields (point_id, phase), giving the phase enum values, noting confirm as optional, and mentioning plan_phase / workflow+downgrade modes, though it leaves those alternate fields' structure undefined.

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 opens with a concrete verb and resource ("Move a point") and enumerates the controlling fields (point_id, phase with the four allowed values), so the agent knows exactly what operation this performs. It is distinguishable from siblings like do_train or do_decide, though the meaning is partly carried by opaque internal section references (§6.4, §15.6, §15.8).

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 gives real gating conditions for two modes: shadow requires a trained local_legacy probe or hosted key plus budget plus remote_ok; serve requires the §6.4 checks plus confirm:true and advises asking the user first. However, it never names an alternative tool or states when not to use this one, so routing guidance is implied rather than explicit.

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