Stage Cmd

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

With no annotations, the description carries the full behavioral burden. It does disclose two meaningful traits: the call blocks waiting for the page's answer up to 'timeout seconds', and typed-op types are refused with that op's name. It does not disclose side effects, permissions, or what happens on timeout, so gaps remain.

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 description is short—two sentences—so it is not bloated. However, the front-loaded phrase 'A page command that has no op of its own yet' is convoluted and the parenthetical nested clause makes the key selection rule hard to parse.

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 four parameters including a nested 'fields' object, a required 'scene', and no annotations, the description is too thin. It leaves 'scene' undocumented and never clarifies what a page command is or what fields are accepted, though the existing output schema does relieve the need to explain return values.

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 mentions 'type', 'fields', and 'timeout seconds' but never explains the required 'scene' parameter, nor the format or meaning of 'type' or 'fields'; it does not specify units/behavior of timeout beyond seconds.

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 identifies a resource ('a page command') and a specific constraint ('that has no op of its own yet, by its type with its fields'), plus an escape-hatch role. However, 'page command' and 'op' are never grounded in plain terms, so the core action remains vague despite some sibling differentiation via the typed-op refusal rule.

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?

The parenthetical 'the escape hatch; a type that has a typed op is refused with that op's name' implies when to use it (types without typed ops) and when not to (types with typed ops). This is useful selection context but is buried and does not explicitly name the alternative tools an agent should prefer.

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