sftp_upload

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

Annotations already declare destructive/openWorld, but the description adds material behavior the agent cannot infer: overwrite dialogs are left for the human and this tool never approves them, timeout does not cancel the transfer, and credential stores (~/.ssh, ~/.aws, keychains) are refused, with TERMIUS_UPLOAD_ROOTS able to further narrow allowed directories. That is exactly the kind of failure-mode and policy context annotations cannot express.

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 purpose is front-loaded in sentence one, and each subsequent sentence carries distinct operational information — no filler or restatement. The prose is dense and slightly run-on (parenthetical examples, UI pane instructions crammed mid-paragraph), which costs a bit of scannability.

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 destructive, open-world transfer with no output schema, the description covers prerequisites, refusal policy, dialog handling, and timeout recovery, and it implies the return value ('the returned ID') that feeds sftp_transfer_status. It stops short of describing the transfer result shape or how end/error events surface to the caller, a minor gap given no output schema exists.

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?

With 0% schema description coverage the description must carry all four parameters, and it does most of the work: sftp_session is tied to list_sftp_sessions, remote_directory is tied to the pane navigation step, and local_path is constrained to a single regular file. The timeout parameter is only obliquely addressed ('Timeout does NOT cancel') with no unit or what stage it bounds, leaving one gap.

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 first sentence gives a specific verb and resource — 'Upload one local regular file through Termius' native SFTP transfer queue' — including the cardinality constraint (one file) and the transport used. It is immediately distinguishable from siblings like sftp_transfer_status (status polling) and list_sftp_sessions (session discovery), both of which it names.

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?

Explicit prerequisites and routing are given: use the exact session ID from list_sftp_sessions, set one pane to Local, and navigate the remote pane to remote_directory first. It also states the critical when-not: on timeout do not blindly re-upload, follow sftp_transfer_status with the returned ID instead.

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