dm_promote

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

With no annotations, the description carries the full burden and does disclose real gating behavior (credentials, budget, remote_ok, trial-passed requirement for downgrade) and the need for user confirmation before serve. It omits side effects, reversibility/rollback, and what happens when checks fail, which matters for a state-changing operation.

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 bracketed signature puts the required fields and phase enum up front, and every sentence adds a distinct rule. It is dense and telegraphic, however, relying on abbreviated spec citations that cost more decoding effort than they save.

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?

Return values are covered by the output schema, and the description covers the promotion gates well. For a tool this intricate it still leaves out failure behavior, ordering of the §6.4 checks, and the semantics of the single nested `payload` wrapper, all of which an agent needs to invoke it correctly.

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% and the actual schema is an opaque untyped `payload` object, so the description must supply all parameter meaning. It does enumerate fields with required markers (point_id*, phase*) and an inline enum (collect|shadow|serve|paused), but it never states that these are keys inside `payload`, and it mixes mode fields (plan_phase, workflow, downgrade) into the same flat notation.

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?

It states a verb and resource ("Move a point") and names the three modes (phase move, plan_phase move, workflow downgrade). However, the vocabulary is heavy domain jargon (point, phase, probe, tiered, remote_ok) with no glossary, and the meaning is partially deferred to opaque section references (§6.4, §15.6, §15.8), so an agent cannot fully tell what it does without outside docs.

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 concrete preconditions per target phase: shadow requires a trained probe or hosted key + budget + remote_ok, and serve requires all §6.4 checks plus confirm:true with an explicit "ask the user first" instruction. It also routes between modes via plan_phase and workflow+downgrade, though it never explicitly says when NOT to use it versus sibling tools like dm_train or do_promote.

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