Write Raw Terminal Input

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered; the description still adds real hazard context beyond them — shell lines follow target history and an empty Enter may silently repeat the previous command, both surprising side effects on a destructive tool. It misses the lease/permission precondition implied by the terminal_write_leased sibling and the lease tools.

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-loaded with the core verb and the terminal_exec alternative, which is good, but it then sprawls across four topics (encoding, shell history, U-Boot probing, CLI file-transfer workflow) in semicolon-chained clauses, and the CLI-environment sentence sits awkwardly inside a tool description. Every sentence is informative, but the structure is dense and shifts subject abruptly.

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 an output schema, full annotation coverage and 100% param coverage, the description covers the remaining burden well: hazards, sibling routing, and the file-transfer escape hatch. The notable omission is the lease model and the existence of terminal_write_leased, which matters for a destructive write tool.

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 100% and both required params (session_id, data) plus the encoding and actor enums are documented in-schema, including the 1 MiB decoded cap and no-trailing-newline behavior. The description's 'raw UTF-8, hexadecimal, or base64' mirrors the encoding enum rather than adding semantics, so the baseline 3 is right.

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 specific verb (write) and resource (raw UTF-8/hex/base64 bytes to a terminal session) and immediately distinguishes the sibling it is not: 'shell lines follow target history, so use terminal_exec at an idle Bash prompt.' An agent can select between terminal_write, terminal_exec and terminal_enter_uboot without opening any schema.

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?

Explicit positive and negative guidance: use at a verified idle U-Boot prompt, use terminal_enter_uboot for countdown interruption, do not send empty Enter to probe, do not build Base64/heredoc uploads — route those through channelterm file send plus terminal_wait_file_transfer. The one gap is the closest sibling: terminal_write_leased is never mentioned, so whether a lease is required before calling this is left ambiguous.

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