Semantic Cache MCP

Overview Schema Source Related Servers Discussions Admin

Write

write

Create or replace entire file content, append text, or preview changes before committing. Refreshes the cache so later reads and searches see the new text.

Instructions

Create a file or replace its entire contents.

Use this for new files or full rewrites; for localized changes prefer edit or batch_edit. Status is created for a new path or updated for an existing one; an update reports diff_state, and includes the diff against the previous content only when you ask with show_diff. A dry_run writes nothing and says so: the status is would_create/would_update and dry_run: true comes back with it. Writing refreshes the cache so later reads, grep, and search see the new text.

A full write supplies the whole file, so the content_hash it returns is claimable. An append only adds a tail: pass known_hash to show you held the rest, or you get file_hash instead. auto_format reports file_hash too — the formatter's output is not what you sent.

Input Schema

TableJSON Schema

Name	Required	Description
`path`	Yes	File path to create or replace (absolute, or relative to root).
`append`	No	Append `content` to the end of the file instead of overwriting.
`content`	Yes	Full file content, or the text to append when `append=true`.
`dry_run`	No	Preview the result without writing.
`show_diff`	No	Return the unified diff even on a deterministic write.
`known_hash`	No	The `content_hash` you hold for this file. Only needed for `append`, to prove you hold the part you are not resending.
`auto_format`	No	Run the formatter after writing.
`create_parents`	No	Create any missing parent directories.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.6.0Sep 7, 2026

addedInput schema / properties / known_hash

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The `content_hash` you hold for this file. Only needed for\n`append`, to prove you hold the part you are not resending."
+}

changedOutput schema / (root)

Previous value: -{
-  "properties": {
-    "bytes_written": {
-      "anyOf": [
-        {
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Bytes Written"
-    },
-    "content_hash": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Content Hash"
-    },
-    "created": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Created"
-    },
-    "diff": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Diff"
-    },
-    "diff_omitted": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Diff Omitted"
-    },
-    "diff_state": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Diff State"
-    },
-    "diff_stats": {
-      "anyOf": [
-        {
-          "additionalProperties": true,
-          "type": "object"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Diff Stats"
-    },
-    "dry_run": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Dry Run"
-    },
-    "from_cache": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "From Cache"
-    },
-    "path": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Path"
-    },
-    "status": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Status"
-    },
-    "tokens_saved": {
-      "anyOf": [
-        {
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Tokens Saved"
-    },
-    "tokens_written": {
-      "anyOf": [
-        {
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Tokens Written"
-    },
-    "truncated": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Truncated"
-    }
-  },
-  "title": "WriteResponse",
-  "type": "object"
-}New value: +null

Changed7 schema fields changedv0.5.1Jul 13, 2026

addedInput schema / properties / append / description

Added value: +"Append `content` to the end of the file instead of overwriting."

addedInput schema / properties / auto_format / description
```
Added value: +"Run the formatter after writing."
```

addedInput schema / properties / content / description

Added value: +"Full file content, or the text to append when `append=true`."

addedInput schema / properties / create_parents / description
```
Added value: +"Create any missing parent directories."
```

addedInput schema / properties / dry_run / description

Added value: +"Preview the result without writing."

addedInput schema / properties / path / description

Added value: +"File path to create or replace (absolute, or relative to root)."

addedInput schema / properties / show_diff / description

Added value: +"Return the unified diff even on a deterministic write."

Addedv0.4.5May 4, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and fully delivers. It discloses returned status values (`created`, `updated`, `would_create`, `would_update`), the `dry_run: true` signal, cache-refresh side effects, and the different hash-return behavior for full writes, appends, and `auto_format`. This is far more than a generic mutation description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and usage rule, then organized into hash and side-effect semantics. Despite its length, every sentence adds operational detail that an agent needs, and none merely repeats the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 8 parameters, no output schema, and no annotations, the description is exceptionally complete. It explains the outcome variants, return-value semantics for diff, dry-run, append, and auto_format, and side effects on the cache. No critical behavioral dimension is left for the agent to infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining how `known_hash`, `show_diff`, `dry_run`, `append`, and `auto_format` affect the response and the claimability of hashes. It earns a 4, though a full parameter-by-parameter walkthrough is not needed given the schema already documents each field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb and resource: 'Create a file or replace its entire contents.' It explicitly distinguishes this tool from siblings by saying localized changes should use `edit` or `batch_edit`, so an agent can immediately tell which tool fits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states when to use `write` ('new files or full rewrites') and when not to use it ('for localized changes prefer `edit` or `batch_edit`'). It also explains the append path and dry-run behavior, giving the agent actionable routing and usage context beyond the schema.

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

Deploy Server

Write

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools