write_file

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that writing completely replaces the existing content and that the file must already exist (via the path parameter description). This discloses the destructive nature of the operation. However, it doesn't mention what happens if the file does not exist, permissions required, or whether changes are atomic, but for a simple file write, this is adequate.

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 with the key action, but includes redundant elements: the Chinese translation duplicates the English content, and the keyword list repeats information already in the description and schema. While structured logically (action, workflow, distinction), it could be more concise by removing the bilingual duplication and excessive keywords. It earns a 3 for being somewhat verbose but still organized.

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 simple (2 params) and has a rich output schema, so the description need not cover return values. It covers the core aspects: what it does, the destructive replacement, the required existence of the file, and the recommended workflow. For a write tool, this is quite complete, though it could mention error cases (e.g., file not found) for extra clarity. Overall, it's contextually complete for the complexity.

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 schema description coverage is 100% and both parameters (path and content) have detailed descriptions with examples. The tool description adds little beyond the schema for parameter semantics; it repeats the replacement behavior but doesn't add new parameter-specific meaning. The baseline of 3 is appropriate since 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?

The description clearly states the tool's action ('WRITE OR UPDATE content to existing file') with the specific effect of completely replacing current content. It explicitly distinguishes itself from 'create_file' for new files, and the verb 'write' is specific to the resource. This makes the purpose unambiguous and differentiates it from sibling tools like read_file and create_file.

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 explicit usage guidance: it tells the agent to read the file first, modify content, then write back, and directly instructs to use 'create_file' for new files. This clearly indicates when to use this tool versus the alternative. The keyword list also reinforces the intended use cases (update, modify, save, edit).

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