upload_file

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does add useful context: local_path is relative to the MCP server, host_name defaults from SSH_HOSTS config, and the return includes file size or error. However, it fails to disclose critical mutation behaviors such as overwrite semantics, directory creation, permission requirements, or failure handling for missing local files. This is a significant gap for a file-transfer tool.

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 concise and well-structured: a one-sentence summary, a bulleted Args section, and a Returns line. Every part is informative, with no filler or redundancy. The format is easy to scan and front-loads the core purpose.

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?

The description covers the essential information for invocation: what the tool does, all parameters with detailed semantics, and the return format. It also provides useful context about the execution environment and host configuration. The main gap is missing behavioral details like overwrite behavior, but for a simple upload tool, the provided information is sufficient for an agent to select and invoke it correctly. An output schema exists, so return values are further documented.

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. It fully compensates with an Args block that explains each parameter in detail: local_path is an absolute path on the MCP server, remote_path is a destination absolute path, and host_name is a named host from SSH_HOSTS config with a default. This adds meaning beyond the bare schema and even clarifies ambiguous aspects like 'absolute' and the default host behavior.

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 a specific verb and resource: 'Upload a local file to the remote server via SFTP.' This clearly distinguishes the tool from siblings like download_file (remote to local) and write_file (writing content directly to a remote file). The direction (local->remote) and protocol (SFTP) are explicit, making the purpose unambiguous.

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 provides clear context for when to use the tool: when you need to transfer a local file to a remote server. It does not explicitly mention alternatives or exclusions, but the purpose is specific enough that the intended use case is clear. The description also notes host_name behavior, which aids correct selection. Lacks explicit 'when not to use' guidance, so not a 5.

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