Stage Waypoints Clear

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

With no annotations, the description must carry the behavioral burden. It does disclose the outcome surface ('Page replies {cleared}' and 'Emits: nothing'), which tells the agent what comes back. It omits whether the deletion is irreversible, whether it needs confirmation, and which scene state is affected beyond 'pins'.

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?

Very compact and front-loaded: the removal semantics come first, the kind values second, then return/emission notes. Minor waste in that 'Page replies {cleared}' and 'Emits: nothing' partially restate output behavior, and the 'page command: waypoints_clear' metadata is implementation detail of limited use to an agent.

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 the description needn't explain return values, yet it does note the reply shape, which is fine. What is missing for a two-parameter destructive tool with no annotations: the meaning of 'scene', any note on irreversibility, and any routing against the single-waypoint remove sibling.

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 for both parameters. It does add the value vocabulary for 'kind' (note | todo | done | look), which the schema lacks entirely, and that is a real contribution. The required 'scene' parameter, however, is never mentioned, leaving half the parameter surface undocumented.

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 concrete verb and resource: remove pins, either all of them or all of one kind. The scope distinction (every vs. filtered by kind) is genuinely informative. It does not, however, differentiate itself from nearby siblings like stage_waypoint_remove or stage_markers_clear, so an agent must infer that this one is the bulk-clear.

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?

'Remove every pin, or only those of one kind' implies the when-to-use split between the all-case and the kind-case, which is real guidance. But there is no explicit statement about when to prefer this over stage_waypoint_remove (single removal) or stage_markers_clear, and no prerequisites or warnings about irreversibility.

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