pio_upload_ota

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

With zero annotations, the description carries the full burden and delivers richly: it discloses the default pre-flight resolve-and-ping behavior, that the default path triggers a build matching the current config, the direct-file path when build=false, the filesystem mode, a four-case failure-to-cause mapping (no_response, auth_failed, no_callback, device_rejected), and the build_only/read_only policy block. This far exceeds what annotations would typically provide.

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 long but every sentence earns its place, flowing logically from purpose to key params to execution modes to failure mapping to policy. The failure-to-fix mapping is arguably beyond minimal need but serves a real diagnostic purpose for agents. Slightly dense, but well-organized and front-loaded.

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?

For a complex 9-parameter write tool with no annotations, the description covers the essential ground: purpose, key parameter semantics, execution modes, error causes, and policy restrictions. The output schema presumably documents return values. The only real gaps are timeout_s and project_dir semantics — minor, but preventing a fully complete score.

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%, so the description must compensate — and it does for most parameters: host (IP or name.local), port (3232/8266 defaults), auth (ArduinoOTA password), build (build fresh image vs send existing binary), filesystem (SPIFFS/LittleFS), and verify_reachable (default resolve and ping). Gaps remain: timeout_s and project_dir are never explained, and env is only implicit via .pio/build/<env>/.

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 opens with a specific verb and resource: 'Flash firmware over Wi-Fi to an ESP32/ESP8266 running ArduinoOTA (espota).' This precisely identifies what the tool does and, through the 'over Wi-Fi'/ArduinoOTA qualifiers, distinguishes it from siblings like pio_upload (presumably wired/serial) and pio_flash_and_verify without ambiguity.

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 clear context for when the tool applies (Wi-Fi OTA to ArduinoOTA-capable devices) and documents mode selection (default build, build=false, filesystem=true). However, it never explicitly contrasts against siblings — the differentiation from pio_upload is implied by 'over Wi-Fi' rather than stated, and no 'when-not-to-use' guidance is provided.

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