Create or overwrite a file while preserving existing encoding, applying .editorconfig rules for new files, and creating parent directories automatically.
Create or overwrite a file. Preserves existing encoding, uses .editorconfig for new files, and creates parent directories.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Alias for file_path | |
| content | Yes | Content to write to the file | |
| file_path | No | File path; relative to workspace/MCP root |
Changes observed during successful MCP inspections.
v0.9.7Input schema / properties / file_path / descriptionPrevious value: -"File to write. Relative paths use the configured workspace or MCP client root"New value: +"File path; relative to workspace/MCP root"v0.9.5Input schema / properties / file_path / descriptionPrevious value: -"Absolute path to the file to write"New value: +"File to write. Relative paths use the configured workspace or MCP client root"v0.8.7v0.7.12Output schema / (root)Previous value: -{
- "additionalProperties": false,
- "properties": {
- "result": {
- "type": "string"
- }
- },
- "required": [
- "result"
- ],
- "type": "object"
-}New value: +nullv0.4.2Does 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 does well by revealing important side effects: overwriting, preserving existing encoding, applying .editorconfig for new files, and creating parent directories. It stops short of mentioning irreversibility risks, permissions, or failure behavior, but the core destructive nature is communicated through 'overwrite.'
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 focused sentence that front-loads the primary action ('Create or overwrite a file') and then adds three compact behavioral details. Every clause earns its place, with no filler or repetition of schema 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?
For a simple write tool, the description covers the essential contextual details: overwrite semantics, encoding handling, editorconfig behavior, and directory creation. It lacks an explicit note about destructive impact or comparison to edit/patch, but the schema covers parameter requirements and the description provides enough behavioral context 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 the structured fields already document content, file_path, and path as an alias. The description adds no parameter-specific detail beyond the schema, which matches the baseline of 3; no compensation is needed.
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 a specific verb and resource ('Create or overwrite a file') and further specifies exact behavior: preserving encoding, applying .editorconfig for new files, and creating parent directories. This clearly identifies it as a whole-file write operation and differentiates it from siblings like edit, patch, and multiedit, which imply targeted changes.
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 the tool—creating new files or fully overwriting existing ones—but does not explicitly say when not to use it or mention alternatives such as edit/patch for partial modifications. An agent can infer the use case from 'Create or overwrite a file,' but there is no direct routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.