Encryptor MCP

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

Annotations already mark it non-read-only and non-destructive; the description adds genuinely new behavioral facts: existing content is preserved and the operation is undoable, and that content is appended exactly with no automatic newline. That last point is behavior an agent cannot infer from annotations or schema and matters for correctness. Minor gap: no mention of size limits or failure modes.

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 compact sentences with no filler; the core action and the newline guidance are front-loaded. Slight redundancy with 'exactly as given' echoed from the schema keeps it from a 5.

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 annotations covering the safety profile, an output schema covering return values, and full parameter documentation, the description only needs to convey scope and the newline nuance, which it does. The remaining omission is not routing the agent to write_file for new files or whole-file writes.

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 all four parameters are documented in the schema itself. The description reinforces the 'content' append semantics with the line-break rule, but that rule is already stated in the content parameter description, so the added value is marginal.

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?

States a specific verb (append/add text) and resource (existing text file) with the crucial 'existing' qualifier that pins down the scope. It does not explicitly name write_file as the counterpart for new or full-file writes, so the sibling differentiation is only implicit.

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 phrase 'existing text file' implies you should already have a file, nudging the agent away from write_file for creation, and 'previous contents are kept' plus 'can be undone' hint at when this is the safer choice. But there is no explicit when-to-use, when-not-use, or named alternative among the many siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description adds real value by disclosing that the tool launches a browser UI and that 'the link is never shown here' — output behavior the agent could not infer from the annotations or empty schema. The qualifier 'On this computer' hints at environment-dependent behavior without clarifying what happens elsewhere, which is the only gap.

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?

Purpose is front-loaded in the first clause, and the second sentence carries the one behavioral fact that matters most (browser launch, no link returned). The parenthetical enumeration is dense but each item earns its place by mapping to a sibling tool; slightly long but not padded.

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 no parameters, an output schema present, and annotations covering the safety profile, the description supplies what remains: what the control center contains and that it opens in the user's browser. The only unresolved ambiguity is the 'On this computer' scoping, which leaves the remote/non-local case unstated.

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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate and it does not mislead about inputs.

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?

States a specific verb+resource ('Open the Encryptor MCP control center for the user') and then enumerates the capabilities it exposes (vaults, undo, trash, settings). An agent can distinguish it from siblings like 'unlock', 'undo', and 'trash_list' because those are named as things living inside the control center rather than competing actions.

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 the routing rule: the sibling operations (unlock, lock, undo, trash, settings) can be surfaced to the user through this control center, and 'opens in the user's own browser' signals a user-facing handoff rather than an AI-executed action. It never states an explicit when-to-use/when-not clause, so it stops short of a 5.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds genuinely new context: the copy stays encrypted throughout. It still omits what happens when the destination is occupied or whether the copy is undoable, but the encryption guarantee is real added value beyond structured fields.

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?

A single front-loaded sentence with the core action first and the scoping constraint immediately after. The parenthetical about encryption earns its space; nothing is padded.

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?

An output schema exists, so return values need no explanation, and the schema covers all four parameters thoroughly. The description supplies purpose and the encryption/same-vault constraints, leaving only failure modes (destination exists, permissions) unstated.

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 100% and all four parameters are documented in the schema, including the 'must be free' constraint on 'to'. The description adds no parameter-level detail, so the baseline of 3 applies.

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?

States a specific verb and resource ('Copy a file') plus the destination scope ('to a new name or folder in the same vault'). The copy-vs-move distinction is implied by the verb and the same-vault constraint, but the sibling 'move' tool is never named, so an agent must infer the routing 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?

Usage is only implied: 'in the same vault' tells the agent this is an intra-vault operation and hints that cross-vault copies need something else, but there is no explicit when-to-use, no prerequisites, and no named alternative versus 'move' or 'write_file'.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, establishing a safe local read. The description adds the 'open vault' precondition and clarifies the encrypted-path input format as seen in a sync app or file browser, which is genuinely useful context. It doesn't contradict annotations.

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?

It is a single short sentence with no filler, so length is fine. But it reads as an incomplete sentence about the input format rather than a front-loaded statement of what the tool does, weakening structure.

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, return values needn't be explained, and annotations cover safety. For a simple two-parameter read tool the description is minimally adequate, but the missing verb and lack of routing against sibling path/folder tools leave gaps.

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 100%, and the schema already documents both parameters with examples. The description largely repeats the encrypted_path example ('d/AB/CDEF.../name.c9r') rather than adding new meaning, so baseline 3 applies.

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 names the resource and outcome (an encrypted path resolves to a 'real path') but is phrased as a noun fragment with no verb, so the action is inferred rather than stated. It doesn't distinguish this tool from siblings like locate or file_info, which also deal with paths.

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 phrase 'inside an open vault' implies the vault must already be unlocked, which is a useful prerequisite. However, there is no explicit guidance on when to use this versus locate, list_folder, or file_info, and no when-not conditions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description reinforces it with 'this can't be undone' and adds genuinely non-annotated context: approval happens outside the chat. No mention of what the response looks like, but the output schema exists.

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 tight sentences, front-loaded with the destructive scope and then the irreversibility/approval constraint. No filler.

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 mutation with full annotation coverage, an output schema, and 100% parameter coverage, the description supplies everything else an agent needs: scope of deletion, irreversibility, and the out-of-chat approval flow.

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 100%, so the schema already documents 'item', 'vault' and 'purpose' in detail. The description restates the empty-item semantics but adds no format or value detail beyond the schema — the baseline 3 applies.

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?

States a specific verb and resource — permanently deleting either one trashed item or the entire trash — and the 'for good' phrasing distinguishes it from the soft-delete sibling 'trash'. It does not name the sibling alternatives explicitly, so routing relies on the agent inferring the contrast.

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?

Gives a clear conditional: pass an id from trash_list for one item, leave empty to wipe the whole trash. It also states the user approves the action outside the chat, which tells the agent not to seek in-chat confirmation, but it does not explicitly contrast with 'trash' or 'restore_version'.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact: the operation requires an open vault. It does not disclose error behavior for missing paths or the shape of the encrypted-location value beyond what the output schema already provides.

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?

A single well-formed sentence that front-loads the resource and then lists the concrete returned fields. No filler words or redundancy; every clause adds information.

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 annotations covering the read-only profile, the description need not explain return values. It supplies the open-vault precondition and the field list, which is sufficient. A note on behavior when the path does not exist would make it fully complete.

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 100%, so both the vault and path parameters are fully documented in the schema with examples. The description adds no syntax, format, or edge-case guidance beyond what the schema already states, so the baseline 3 applies.

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?

Names a specific verb/resource (details of a file or folder) and enumerates the returned fields (kind, size, last change, storage location), which clearly separates it from read_file or list_folder. It does not explicitly name a sibling alternative, keeping it short of a 5.

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 phrase 'in an open vault' implies the prerequisite that the vault must first be unlocked (via the unlock sibling), which is useful context. However, there is no explicit statement of when to use this versus list_folder, find, or read_file, and no exclusion conditions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that matching is substring-based and case-insensitive, and that the vault must be open, which is useful behavioral context, but says nothing about result ordering, truncation at the limit, or failure modes.

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?

A single, front-loaded sentence with no filler; the verb and resource come first and the scope qualifier follows. It is efficient, though the terse phrasing leaves room for a short routing clause to a sibling.

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?

An output schema exists, so return values need not be explained, and the schema fully documents the parameters. The main gap is guidance on selecting this tool over the similar locate sibling, which is not covered anywhere.

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 100%, so all four parameters (limit, vault, folder, name_contains) are already fully documented in the schema. The description reinforces the matching behavior of name_contains but adds no syntax or constraint detail beyond what the schema provides, so the baseline 3 applies.

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?

States a specific verb (find), resource (files and folders), and matching semantics (name contains text, any case) plus scope (open vault). This is clearly distinguishable from siblings like read_file or list_folder, though it gives no hint about how it differs from locate, another likely search-like sibling.

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 phrase 'in an open vault' implicitly signals the vault must be unlocked, which is a weak usage hint. There is no explicit when-to-use guidance and no mention of alternatives such as locate or list_folder, which an agent would need to choose correctly.

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

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

Annotations already carry readOnlyHint=true and openWorldHint=false, so the safety profile is pre-established; the description usefully adds that repairs are not performed here but by the user via the control center, and that the vault must already be open. It does not disclose cost or duration for large vaults, which is the main remaining behavioral gap.

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 purpose and scope, with no filler. The 'like Cryptomator's own health check' clause is mildly redundant with the tool name but it does convey the exact check semantics rather than restating the name.

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?

An output schema exists, so return values need not be explained, and the prerequisite vault state plus the read-only boundary are covered. What remains unstated is scope/pagination for very large vaults, a minor omission for a single-parameter read tool.

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?

Only one parameter, and the schema already documents it at 100% coverage, including that the name must match the vaults listing. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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?

States a specific verb and resource — checking the structural integrity of an open vault — and enumerates exactly what is verified (folders, long names, files) plus files that were cut or changed. No sibling tool (find, recent_changes, file_info) does this, so an agent can distinguish it without opening a schema.

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 names the precondition ('an open vault') and closes off the repair path by directing it to the control center, which implicitly points the agent at the control_center tool for fixes. It does not name alternatives for the not-open case (e.g. unlock) or state when a health check is worth running, so it stops short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description still adds the genuinely useful state requirement that the vault must be open, and names what the result contains; it does not need to explain returns since an output schema exists.

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 compact sentences: the operation and its result are front-loaded, then the one parameter whose syntax is non-obvious. Nothing is wasted and nothing important is buried.

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 simple read-only, two-parameter listing tool with a 100%-covered schema and an output schema, the description covers purpose, output content and the open-vault precondition. The only missing element is routing guidance relative to siblings such as find or file_info.

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 100%, so vault and folder are both fully documented in the schema. The description's restatement of the folder path format and the '/' convention duplicates the schema rather than adding new meaning, so the baseline 3 applies.

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 gives a specific verb (List) and resource (a folder), and further specifies the payload an agent will get back: names, kinds and sizes. That is enough to separate it from read_file or find in practice, though it never names a sibling tool to contrast against, which keeps it short of a 5.

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 phrase 'in an open vault' implies the vault must already be unlocked, which is a real usage precondition, but the description never says when to prefer this over find, file_info or locate. Usage is only implied, not stated.

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

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

The description goes beyond the simple read-only annotation by specifying that the location is 'stored encrypted on disk' and is 'relative to the vault's folder.' This crucial detail helps the agent understand the nature of the output path.

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 highly concise, immediately stating the primary function and followed by a single, relevant use case ('handy for sync conflicts or backups'). There is no wasted language.

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 tool is complete. It defines exactly what information the tool provides (the encrypted disk location) and why that information is valuable, allowing an agent to invoke it with the necessary context (vault name and file path).

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 100%, meaning the input schema adequately defines 'path' and 'vault'. The description provides a functional context but does not add specific semantic meaning beyond what the structured schema already covers, meeting the baseline requirement.

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 clearly states the tool's function: locating the encrypted on-disk storage path of a specific file or folder within an open vault. This specific function is highly distinct from sibling tools like 'read_file' or 'find', which retrieve data or metadata.

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 provides excellent context for when to use the tool by naming specific scenarios: 'handy for sync conflicts or backups.' While it doesn't explicitly exclude all other tools, the highly specialized nature of locating the encrypted storage location makes its usage guidelines clear.

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

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

The description adds real behavior beyond the annotations: locking wipes the keys from memory and applies immediately ('now'), and empty input means all open vaults. Annotations already cover the safety profile (idempotent, non-destructive, not read-only), so this extra effect disclosure is meaningful. It does not state reversibility (unlock restores access) or any auth requirement.

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?

A single front-loaded sentence with the action first and the key side-effect second. Nothing is padded or repeated.

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 one-parameter, output-schema-backed tool this description covers purpose, scope, and the primary side effect. The main omission is the relationship to 'unlock' and when locking is appropriate, which a sibling-aware agent would benefit from.

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 100%, so the single 'vault' parameter and its empty-string default are already fully documented. The description restates the empty-default semantics, adding no syntax or format detail beyond the schema.

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?

States a specific verb (lock) and resource (vault), and clarifies scope: a single named vault, or all open vaults when the argument is empty. It is implicitly the inverse of the sibling 'unlock', though it never names that sibling explicitly.

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?

Usage is implied rather than stated - an agent can infer this is the tool for securing a vault, and the description distinguishes the two scope cases. There is no explicit when-to-use vs when-to-use-something-else guidance or mention of a prerequisite state (vault must be unlocked).

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent operation, so the safety profile is covered. The description adds the precondition that the parent must exist, which the annotations cannot express. It does not say what happens if the folder already exists or where the folder is created relative to the vault.

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?

A single sentence with zero filler, leading with the action and immediately qualifying it with the one precondition an agent needs. Nothing to trim.

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?

Output schema exists so return values need no explanation, and all three required parameters are documented. What is left implicit is the collision behavior (annotations mark it non-idempotent, implying failure on an existing folder) and any vault-level scoping nuance.

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 100%; every parameter (path, vault, purpose) is documented in the schema, including path's own restatement of the parent-must-exist rule. The description adds no syntax, format, or default information beyond that baseline.

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?

States a specific verb and resource ('Create a folder'), which is unambiguous against every sibling in the list (write_file, copy_file, move, list_folder). It does not explicitly name when a sibling such as write_file would be preferred, but the purpose itself is unmistakable.

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 only guidance is the stated prerequisite that the parent folder must exist, which is useful context for invocation but not a when-to-use rule or an alternative comparison. No exclusions or sibling routing are offered.

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

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

Although annotations cover the safety profile, the description adds vital behavioral context by explicitly stating 'Nothing is overwritten.' This proactive assurance significantly reduces the risk profile and informs the agent about the atomicity of the move operation.

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 definition is highly concise. It front-loads the core action and uses the single sentence structure to deliver the primary function and the most critical behavioral constraint without unnecessary phrasing.

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 100% schema coverage, the addition of the behavioral guarantee ('Nothing is overwritten') provides the necessary high-level operational completeness required for the agent to use the tool safely and correctly.

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?

Since schema description coverage is 100%, the description's primary function is reinforcement. The sentence about the new place needing to be free reiterates a condition already defined in the `to` parameter schema, making it adequate but not adding new semantic meaning.

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 uses clear verbs ('Move or rename') and identifies the resource ('file or folder'). It successfully distinguishes its function from other siblings by defining its scope as confined 'within one vault'.

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 clearly states a critical operational constraint: 'Nothing is overwritten: the new place must be free.' This acts as a crucial guideline on when the tool is expected to succeed or fail, directing the agent's input parameters.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile, but the description adds meaningful context: the purpose string is logged, and pictures/binary files are not returned as text. These are behavioral facts not present in the structured fields.

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?

Compact and front-loaded, leading with the core action before caveats. The compressed phrasing is efficient, though the fragmentary style ('purpose: a few words on why') is slightly terse.

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, return values need no explanation, and the description still covers the key caveat (binary files excluded) and the part-reading mechanism. It omits prerequisites like the vault needing to be unlocked, but 'open vault' hints at this.

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 100%, so the schema already documents all five parameters thoroughly. The description reinforces offset/max_chars for part-wise reading and purpose for logging, but adds no syntax or format details beyond the schema. Baseline 3 applies when the schema carries the load.

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?

States a specific verb and resource ('read a text file from an open vault') and adds a scope boundary by excluding binary files. It does not explicitly distinguish itself from siblings like file_info or find, but the verb+resource is 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?

It implies usage by noting offset and max_chars let you 'read a long file in parts,' which is a real when-to-use cue. However, it never names alternatives (e.g., use file_info for metadata, find to locate a path) or states when-not to use it, leaving routing to inference.

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

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

Annotations already establish that this is a read-only, non-open-world operation. The description adds useful context about the fields returned, but does not go beyond that to explain ordering, pagination, or other behavioral details.

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 a single compact sentence that front-loads the core resource and specifies the returned information. There is no wasted language.

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?

Given the output schema and read-only annotations, the description is largely complete for this simple listing tool. Its main gap is the absence of guidance about when to use it instead of related sibling tools.

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 both parameters are already documented in the input schema. The description does not add parameter-level meaning beyond what the schema provides, which is the baseline expectation here.

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 clearly identifies the resource: recent changes in a vault, and specifies the kinds of information shown (when, app, why, undone). It does not explicitly differentiate this from sibling tools like versions or undo, so it falls short of a 5.

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 no explicit guidance on when to use this tool versus alternatives such as versions or undo. Usage is only implied by the phrase 'latest changes in a vault.'

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

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

The clause 'The current contents are kept too' adds real behavioral context beyond the annotations, clarifying that restore does not overwrite the present file. Annotations already declare destructiveHint=false and non-readOnly, and the description does not address idempotency (idempotentHint=false) or what new version is created.

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 compact sentences, with the core action leading and the non-destructive consequence following. No wasted wording.

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 fully documented parameters, the description only needs to convey the restore semantics and the non-destructive behavior, which it does. Minor gaps around idempotency and resulting change-log entry are acceptable given the annotations and output schema.

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 100%, so all four parameters are documented by the schema itself, including that version_id comes from versions. The description adds no syntax or format detail beyond that, so baseline 3 applies.

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?

States a specific verb and resource ('Put back an earlier version of a file') and ties the version_id to the sibling 'versions' tool, so an agent can distinguish this from listing versions. It doesn't explicitly contrast with undo or versions by name, keeping it just short of full sibling differentiation.

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?

Implies prerequisite flow by noting the id comes 'from versions', which is useful routing, but there is no explicit when-to-use/when-not guidance or comparison against siblings like undo or versions.

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

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

Annotations already declare destructiveHint=false, and the description adds meaningful context: items remain encrypted, are recoverable via undo, and permanent deletion requires a separate user-approved empty_trash. It does not mention vault-lock/auth prerequisites, which is the main remaining behavioral gap.

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 with no waste. The core action is front-loaded, and the reversibility and permanence caveats follow in a natural order.

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 annotations, a full input schema, and an output schema, the description covers the essential behavioral profile for a trash operation. It could be improved by noting whether the vault must be unlocked, but it is otherwise complete for correct invocation.

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 100%, so all four parameters are already documented. The description adds no parameter-level detail beyond what the schema provides, making the baseline 3 appropriate.

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?

States a specific verb (put in trash) and resource (file or folder in the vault), and explicitly distinguishes itself from permanent deletion and from undo. An agent can tell it apart from empty_trash and undo without opening any schema.

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?

Explains the intended use and contrasts it with permanent deletion via empty_trash, and notes recoverability through undo. It stops short of explicitly instructing when not to use it, but the sibling routing is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe-read profile is covered by structured data. The description adds the payload shape (id, original path, deletion time), which is useful but largely duplicates the output schema; it says nothing about ordering, pagination, or behavior on an empty/missing trash.

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?

One front-loaded sentence with zero filler that immediately identifies the resource and the fields returned.

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 one-parameter, read-only list tool with a complete input schema and an output schema, the definition is nearly sufficient; only the routing context (that this precedes empty_trash or restore) is missing.

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% and the single vault parameter is fully documented in the schema, including the example 'Taxes'. The description adds no extra meaning beyond that, so the baseline of 3 applies.

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 names the specific resource (the vault's trash) and enumerates the returned fields (id, original path, deletion timestamp), so the agent knows this is a listing operation, not the trash/empty_trash mutators. It does not explicitly name a sibling or contrast itself with them, which keeps it short of a 5.

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?

There is no statement of when to use this tool versus alternatives such as trash (move to trash), empty_trash (purge), or restore_version. The agent must infer from the name alone that this is the inspection step before emptying or restoring.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds a genuinely useful behavioral guarantee beyond them: it refuses when the file changed since the target change, so newer work is never lost. That refusal condition is the key trait an agent needs and is not in the structured fields.

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 tight sentences with zero filler. The selection logic is front-loaded and the safety constraint follows, making it easy to scan.

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 annotations covering the safety flags, the description supplies the remaining critical context (id source, default selection, refusal-on-conflict). Only the relationship to sibling restore_version is left implicit.

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 100%, so the schema already documents all three parameters, including that an empty change_id means 'undo the latest'. The description's note about the id coming from recent_changes largely restates schema content, so baseline 3 is appropriate.

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?

States a specific verb (undo) and resource (a change), and clarifies the two selection modes: a specific change id or the latest change. It does not explicitly differentiate itself from the sibling restore_version, so it falls short of a 5.

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 when to use it by pointing to recent_changes as the id source and explaining the default-to-latest behavior, but it never states when to prefer undo over siblings like restore_version or versions, nor any exclusions.

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

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

The description discloses critical behavior beyond the annotations: the user types the password locally, never in chat, chooses the unlock duration, and sees the purpose. This is exactly the kind of security-sensitive interaction detail an agent needs.

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 front-loaded and appropriately sized. The final sentence reinforces the security-critical warning, though it repeats the earlier 'never in this chat' point.

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?

Given the two required parameters and the presence of an output schema, the description is complete. It covers the interaction model, password handling, and user-facing purpose without needing to explain return values.

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 100%, so both parameters are already well documented. The description adds only marginal meaning, such as the purpose being shown to the user, but largely repeats what the schema provides.

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 uses a specific verb and resource: asking the user to open a locked vault. It clearly distinguishes this from a direct unlock operation by explaining the user interaction model, so an agent can tell it apart from sibling tools like lock.

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 clearly implies usage when a vault is locked and gives a strong directive: never ask the user for the password yourself. It does not explicitly name alternatives or exclusions, but the context is sufficient for correct selection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context about the data itself (lock status, read-only status, auto-lock behavior) but says nothing about the tool's operation, such as whether it returns a collection or triggers any side effect.

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?

It is a single sentence with no wasted words, but it is not front-loaded with a clear action. The fragment is concise yet leaves the core operation ambiguous.

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?

An output schema exists, so return formatting need not be explained. However, for a zero-parameter query tool, the description should still signal that it retrieves vault states; the vague wording leaves the agent to infer the tool's actual role from the output schema.

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?

The tool takes zero parameters, so there is no parameter semantics to explain. Baseline is 4, and the description appropriately does not introduce irrelevant parameter detail.

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 restates the tool name ('The vaults this app may use') with a list of vault properties, but never states an action verb. An agent cannot tell whether this lists vaults, describes a config concept, or fetches a single vault. It also does not distinguish itself from siblings like unlock, lock, or control_center.

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?

There is no when-to-use guidance at all. The description does not say when to call this versus unlock, lock, or any other sibling, nor does it give prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — results are ordered newest first — which matters for selecting a version, but it says nothing about pagination, limits, or retention.

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?

A single compact sentence with no filler. Front-loading is decent (the resource comes first), though the trailing 'for restore_version' reads as a dangling fragment rather than a clean clause.

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?

An output schema exists, so return-value shape need not be explained, and the ordering hint is a nice touch. However, for a read tool feeding a destructive-side sibling (restore_version), the definition gives no sense of how many versions are returned or what identifiers are needed to restore.

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 100% and both parameters (vault, path) are documented in the schema with examples, so the schema does the heavy lifting. The description adds no parameter detail beyond that, making the baseline 3 appropriate.

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 identifies the resource (earlier versions of a file) and the ordering (newest first), and names the sibling that consumes it (restore_version). The verb is implicit ('lists') and the grammar is slightly compressed ('kept by its changes'), which keeps it short of a fully unambiguous 5, but an agent can tell what this returns.

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?

Linking to restore_version implies the workflow (browse versions, then restore one), but there is no explicit when-to-use or when-not-to-use statement, and no contrast with siblings like file_info or recent_changes that also surface historical data.

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

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

It discloses behavior beyond the annotations in two important ways: stale-write protection ("if the file changed since, nothing is written") and recoverability ("the old contents are kept and the change can be undone"), which reconciles the replace operation with destructiveHint=false. These are exactly the concurrency and reversibility traits an agent needs and that annotations alone can't convey.

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 behavioral content is front-loaded and the sentences are dense with information. The trailing "purpose: ... confirm: ..." fragments read like schema notes grafted onto prose, which is slightly awkward, but nothing is redundant.

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 a 6-parameter schema at 100% coverage, full annotations, and an output schema, the description covers the key ambiguities: create vs replace, version conflict handling, and undo. It is complete enough to call correctly, with only the sibling-routing choice (vs append_file) left implicit.

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 real meaning by tying version to a specific source (read_file/file_info output) and explaining the purpose parameter's destination (change log). The confirm guidance also adds context beyond the field's default of empty.

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?

"Create a text file, or replace one" is a specific verb+resource statement that implicitly separates this from the sibling append_file (append) and read_file (read). It doesn't explicitly name an alternative to contrast with, but the create-or-replace framing is unambiguous enough for an agent to pick the right tool.

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 gives concrete usage rules for the two conditional parameters: pass version only to replace, sourced from read_file or file_info, and pass confirm only after a previous answer requested it. It doesn't cover when to choose this over append_file or move/copy_file, so it stops short of full routing guidance.

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