save_to_downloads

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

With no annotations, the description carries the full burden and does disclose meaningful traits: the operation is a copy (source is not moved), the exact destination subfolder, and a hard source-location restriction. It stops short of stating overwrite behavior when a file of the same name exists, which is the main remaining unknown for a write-to-disk action.

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?

Two sentences, front-loaded with the action and destination, then the constraint. Every clause carries information; nothing is padded or restated from the schema.

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 two-parameter tool with full schema coverage and no output schema, this covers what it does, where the file lands, and the eligibility rule. Missing a note on the result (e.g., whether it returns the destination path) and on same-name overwrites, which matters for an agent retrying a save.

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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning by constraining `path` to a whitelisted directory tree rather than just calling it a full path. It also implies `name` controls the on-device filename, though it does not say what happens on collision.

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?

Uses a specific verb ("Copy a file") with an explicit source (Buddy's Linux) and named destination (Downloads/Buddy), plus the user-facing benefit. It does not name or contrast with a sibling like `share` or `find`, so an agent must infer the boundary itself.

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?

Provides a concrete precondition ("The file must be in your work folder (/root/.buddy/work) or this chat's files"), which is real usage guidance. However it never says when to prefer this over `share` or how to handle files that fall outside the allowed locations, so no alternative routing is given.

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