file_push

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

The annotations declare destructiveHint=true, which signals this operation can modify the device filesystem. The description adds the directionality (host to device) and implies file system mutation at a remote path. The description aligns with the annotations — push is a write/destructive operation, consistent with destructiveHint=true. It doesn't add much detail about overwrite behavior or permission requirements, but the annotations carry much of this burden.

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 a single concise sentence that captures the essential operation. It's appropriately front-loaded and has no wasted words. Could arguably add a bit more context about path format requirements, but for its length it's well-structured.

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 file transfer tool, the description is functional but minimal. It doesn't address potential path format differences, whether relative paths are acceptable, overwrite behavior on the device, or whether the serial parameter is needed for multi-device setups. With an output schema present and 100% parameter coverage, some of this burden is lifted, but the description could add operational context that structured data doesn't capture.

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?

All 3 parameters (serial, localPath, remotePath) have descriptions in the schema (100% coverage), so the schema does the heavy lifting. The description mentions 'host machine' and 'device' which contextualizes localPath vs remotePath semantics. However, it doesn't clarify the serial parameter — whether it's required in multi-device scenarios or optional when only one device is connected.

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 'Push a file from the host machine to the device' with a specific verb (push) and direction (host→device), which clearly conveys the core function. It differentiates from the sibling file_pull, though it doesn't explicitly mention that distinction. The title 'Push File to Device' reinforces the purpose.

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 implies this tool is for file transfer in the host→device direction, which inherently distinguishes it from the sibling file_pull (device→host). However, it doesn't explicitly state when to use it vs alternatives, or mention any prerequisites (e.g., needing an active session via start_session, or the device being accessible via serial). The context of sibling tools suggests session-based operation but this isn't stated.

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