upload_file

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates state. The description doesn't contradict annotations. It adds that the payload is base64-encoded, which is useful. However, it doesn't disclose whether existing files at the path are overwritten, whether directories must pre-exist, permission requirements, or what the output schema / return value indicates.

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?

Single sentence, zero wasted words. Effectively front-loaded with the core purpose. Every word earns its place.

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 an output schema present and a 2-parameter tool, this is a relatively simple operation. The description captures the core write operation, base64 encoding, and destination. However, for a destructive operation (destructiveHint=true), the description could note overwrite behavior or confirm-the-target-before-writing guidance. The simplicity of the tool doesn't warrant a higher score given the missing edge-case behavioral context.

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 carries the full burden for parameter semantics. The description does clarify that content_base64 is a base64-encoded payload, which matches the schema field description. However, it doesn't clarify path semantics (absolute vs relative, format requirements) beyond what the schema's 'Destination path on the controlled computer' already states. The description adds minimal value over the schema field descriptions.

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 'Write a base64 file payload to the controlled computer' uses a specific verb (write) and resource (file payload to controlled computer), distinguishing it from sibling download_file (which reads from the computer). The verb 'write' makes the write-vs-read contrast clear against download_file. It doesn't explicitly say 'upload' but the tool name makes that obvious.

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 is for writing files to the remote machine, contrasting with download_file which pulls files. However, there's no explicit when-to-use guidance, no fformat/path conventions, no note about overwrite behavior or directory creation requirements. The context is clear but exclusions are not stated.

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