toggle_dtr_rts

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

No annotations are provided, so the description carries the full burden. It does disclose the important physical side effect (pulsing DTR/RTS hard-resets the microcontroller) and that pulses have a configurable duration, which is real behavioral value. It does not state whether the serial port is opened/exclusively locked, what happens if the port is busy or missing, whether the line states are left asserted after the call, or whether the reset is disruptive to an active session.

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 structure is well front-loaded: one sentence of purpose followed by a compact per-argument list, with the mode semantics nested under 'mode'. It is appropriately sized for a five-parameter hardware tool. Minor waste: 'default 100ms' restates schema information already present.

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 five parameters, no annotations, and an output schema that covers return values, the description supplies what the structured fields cannot: the mode vocabulary and the physical consequence of each mode. It is nearly complete; the missing pieces are port-exclusivity/prerequisite notes and error-condition behavior, which matter for a tool that manipulates a live hardware port.

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% and the schema carries only bare titles, so the description must compensate — and it largely does, documenting all five parameters and, critically, supplying the enumerated mode values that the schema declares only as a free-form string with a default. Gaps remain: no valid range or constraints for pulse_ms, and no statement that dtr/rts are ignored outside 'custom' mode.

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 opening sentence names a concrete verb and resource ('Control DTR and RTS lines on a serial port') plus the two concrete intents (board reset, bootloader entry). It implicitly separates this from data-oriented siblings like send_serial_command or esptool_command, but never names an alternative, so sibling differentiation is left to inference.

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?

Usage guidance exists at the mode level: each of 'reset', 'esp32_bootloader', and 'custom' is explained with the condition that selects it, which is genuinely useful. However there is no guidance on when to choose this tool over siblings such as esptool_command, send_serial_command, or ftdi_gpio_control, and no stated prerequisites (e.g. the port must not be held by another process, despite a free_serial_port sibling existing).

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