update_stage

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

With no annotations, the description carries the full burden. It discloses that this is a mutating operation and that illegal stage transitions are rejected, which is useful. But it omits critical behavioral details: permissions required, side effects, reversibility, and the roles of the confirm and dry_run flags.

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 single sentence is front-loaded and wastes no words. However, conciseness comes at the cost of under-specification for a five-parameter mutation tool.

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 a mutation tool with five parameters (two required, three optional including confirm and dry_run), no output schema, and no annotations, the description is far too thin. It fails to explain transition rules, dry-run behavior, or confirmation semantics that an agent would need 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%, so the description must compensate. It only loosely implies lead_id and stage; it says nothing about note, confirm, or dry_run. The crucial confirm and dry_run parameters are completely unexplained in both schema and description.

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 and resource: 'Move a lead to a new stage.' This clearly distinguishes it from sibling read/query tools like get_lead or list_hot_leads. It does not explicitly name sibling alternatives, but the action is unambiguous.

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?

Usage is implied by 'Move a lead to a new stage' – use when advancing a lead through stages. However, there is no explicit guidance on when not to use it, what 'illegal transitions' mean, or how confirm/dry_run should be used. No alternatives are named.

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