Run several terminal inputs

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

Goes well beyond the annotations (destructive/openWorld/non-idempotent) by disclosing that the batch is validated before anything is sent, that it halts on the first failing action with screen state reported, that clicks are sent with no preview and require mouse tracking, and how settle/idle timing works. It stops short of stating that typed input into a live shell is irreversible, which is the main behavioral risk for a destructiveHint=true 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?

Front-loads purpose, then a compact bulleted field map, but tucks the critical routing guidance ('use the individual tools') into the final sentence. The bullet list is dense yet each line corresponds to a distinct action type, so little is wasted.

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?

With no output schema, the description covers the return behavior ('get the screen back once at the end', 'reports how far it got, with the screen as it stands') plus failure modes and stop conditions. Combined with the schema's 1-50 action bound and timeout defaults, an agent has everything needed to call 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 coverage is 100%, so the schema already carries the field-level detail and a 3 would be the floor. The description adds value by grouping fields by action type and cross-referencing sibling specs ('same key specs as terminal_press', 'as terminal_scroll'), which the schema does not do; the remaining field docs are largely duplicative of the schema.

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?

Starts with a specific verb+resource ('Send a sequence of inputs in one call and get the screen back once at the end') and immediately names the driving use case. It is clearly distinguishable from the per-keystroke siblings (terminal_type, terminal_press, terminal_click) by being the batched equivalent.

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?

Gives an explicit when ('Use it when you already know the steps') and an explicit when-not with the alternative named ('when you need to look between steps, use the individual tools'). It also maps each action type back to its single-shot sibling (terminal_press, terminal_scroll), so routing is unambiguous.

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