send_text

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

With no annotations provided, the description carries the full burden and covers it well: TX-only behavior, no read, echo behavior on interactive console, non-ASCII '?' substitution, line-ending semantics, and buffer discarding when clear_buffer_first is set. These are exactly the non-obvious behaviors an agent needs to know before invoking.

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 front-loaded with a one-sentence core purpose, followed by the actionable behavioral context and then a terse Args section. Every sentence either constrains behavior, provides an example, or explains a parameter—no filler or redundant restating of the schema.

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?

The tool has no annotations and the description covers operational behavior, parameter meanings, edge cases, and follow-up reads. An output schema is present, so return-value documentation is not needed. Minor missing context includes behavior when the device is disconnected or when a command fails, but these are not essential for correct invocation.

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%, but the description fully compensates: data gets concrete examples ('show version', 'FA014250000', 'ID') and the non-ASCII fallback (sent as '?'), line_ending gets exact values with CR/LF explanations and device guidance, and clear_buffer_first gets a precise behavioral definition. This is more valuable than a typical schema 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 ('Send an ASCII command to the device'), and immediately clarifies scope: 'Writes to TX only; does NOT read.' This clearly separates send_text from read-oriented siblings like read_until_prompt and read_available, and from send_hex for raw byte transmission. No ambiguity remains about what the tool accomplishes.

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 description gives explicit follow-up instructions ('call read_until_prompt (or read_available) afterward') and clear guidance on when to use clear_buffer_first. It also points to send_hex as the alternative for raw bytes. However, it does not explicitly contrast with query_text, which appears to be the natural when-to-use-this-vs-that alternative for command/response exchange.

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