Server exposes 12 tools with complete input schemas and descriptions. However, descriptions are generic and lack LLM-optimized guidance on WHEN to use each tool vs. alternatives. Parameter descriptions exist but are minimal (avg ~40 chars, below 72-char baseline). No output schemas documented, LLMs cannot predict response structure. Error handling is absent; tools return raw subprocess output without recovery guidance. Tool naming is verb-first (good), but several tools (uart_transact, can_transact, i2c_transact, spi_transact) are nearly identical in structure, risking LLM confusion. No tool annotations (readOnlyHint, destructiveHint) despite clear risk stratification (READ_ONLY vs WRITE). Security: device_lua parameter accepts file paths, potential path traversal if not validated.

• Document output schemas for all tools. Example: 'h7tool_status returns {hardware: {board, lcd, display_size}, clock: {year, month, day, hour, minute, second}, uptime_ms: integer}'. This enables LLMs to extract and chain results.
• Rewrite transact tool descriptions to clarify WHEN to use each. E.g., 'uart_transact: Send/receive serial data over UART with configurable baud rate and parity. Use for serial console communication, bootloader protocols, or sensor readout. Returns raw bytes received.' Distinguish from CAN (bus frames), I2C (slave addressing), SPI (clock-based).
• Add error handling with recovery guidance. Wrap subprocess calls in try-except; return structured errors like {error: 'Device not found', recovery: 'Ensure H7-TOOL is connected via USB and powered on. Try h7tool_status to verify connection.'}
• Validate device_lua paths: reject paths containing '..', enforce DEVICE_ROOT prefix, and return clear error if file not found. Document: 'device_lua must be a relative path within the device library (e.g., ST/STM32H7xx/STM32H7x_2M.lua). Absolute paths and parent directory traversal are not allowed.'
• Add tool annotations to schema. Mark uart_transact, can_transact, i2c_transact, spi_transact with destructiveHint: true (they modify device state). Mark read_* tools with readOnlyHint: true. This signals to agents which tools are safe to retry.