save_file

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

With no annotations, the description carries the full burden and does: it discloses that parent directories are auto-created, that images are copied into a sibling assets/ folder and renamed "<document-name>-<timestamp>.<ext>" with a Markdown reference appended, that the on-disk original stays full quality while only the model preview is downscaled, and that the root is a hard sandbox rejecting "../" and out-of-root symlinks. It also pre-empts failure interpretation — empty clipboard still saves text and reports re-screenshot guidance, headless environments report clipboard as unsupported rather than crashing.

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 clipboard rule is stated three separate times (the CLIPBOARD FIRST block, the Images paragraph, and the Clipboard behavior paragraph), and the "never ask the user to paste" instruction is repeated again in the schema. The most important fact — what the tool does — is not front-loaded, appearing only after the clipboard and confirmation sections.

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 4-parameter mutation tool with no annotations and no output schema, the description covers everything an agent needs: write-mode semantics, directory creation, image handling and placement, sandbox limits, path normalization, and how to read the result on clipboard failure. Nothing material is left to inference.

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 meaning beyond the schema: path cleaning behavior (quote stripping, ~ expansion, separator normalization), sandbox containment rules for absolute paths, and the downstream effects of the images array (where files land, how they are named, what gets appended to Markdown). Only the mode and content parameters are left to the schema alone.

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 — "Save text (usually Markdown) into the MemDrive memory library" — and the images paragraph makes clear it also archives binary images, which separates it from read-only siblings like read_file and search_files. The purpose statement is buried in the fourth paragraph behind a clipboard preamble, so an agent must read past a lot of material before learning what the tool fundamentally does.

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?

It gives explicit routing rules for the clipboard case (use images: ["clipboard"] whenever the user mentions a screenshot, never ask for a paste), a mandatory pre-call confirmation workflow with a concrete example, and mode selection guidance ("new" fails when the file exists; "overwrite"; "append" creates when missing). These are when-to-use and how-to-behave rules an agent cannot infer from the schema.

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