Frappe MCP Server

Overview Schema Source Related Servers Discussions Admin

Update a document

frappe_update_doc

DestructiveIdempotent

Updates selected fields of an existing Frappe document by doctype and name, leaving all omitted fields unchanged for partial edits.

Instructions

Update selected fields of an existing document, identified by its doctype and name. Use for partial edits: only the keys present in data change and every other field is left alone. Use frappe_create_doc for records that do not exist yet, and prefer this tool over frappe_delete_doc when a document should be voided rather than removed — setting a status such as 'Cancelled' preserves the audit trail. Behavior: writes to the site, overwriting the previous values of the fields supplied; those old values are not recoverable through this API. Idempotent — repeating an identical call leaves the document in the same state. Validation and DocType hooks run on save, so an update is accepted or rejected as a whole, never partially applied. Documents already submitted (docstatus 1) accept changes only to fields marked 'Allow on Submit'; other edits fail. Requires write permission on the DocType. Parameters: data keys are fieldnames, not form labels. Supplying a child-table field replaces the entire table rather than merging rows, so to amend one row read the document with frappe_get_doc first and send back the complete row list. Fields omitted from data are untouched — there is no way to clear a field except by setting it explicitly to null or an empty string. Returns: {"data": {...}} — the whole document as it stands after the update.

Input Schema

Name	Required	Description
`data`	Yes	Fieldnames and their new values. Only the fields included here are modified; others retain their current values. Passing a child-table field replaces every row in that table. Example: {'status': 'Cancelled', 'remarks': 'Cancelled per customer request'}.
`name`	Yes	The `name` primary key of the existing document to modify (e.g. 'SINV-00001', 'CUST-00001', 'ITEM-00001'). The document must already exist; this tool does not create one.
`doctype`	Yes	The DocType of the document to update (e.g. 'Sales Invoice', 'Customer', 'Item', 'Sales Order'). Case-sensitive and must match the doctype of the existing document.

Output Schema

Name	Required	Description	Default
`data`	Yes	A Frappe document. Keys are DocType fieldnames; child tables appear as arrays of row objects. Always includes `name` (the primary key), `owner`, `creation`, `modified` and `docstatus` (0 = draft, 1 = submitted, 2 = cancelled).

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv1.2.0Nov 2, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / data / description

Previous value: -"Dictionary of field names and their new values. Only the fields included here are modified; other fields retain their current values. Example: {'status': 'Cancelled', 'remarks': 'Cancelled per customer request'}."New value: +"Fieldnames and their new values. Only the fields included here are modified; others retain their current values. Passing a child-table field replaces every row in that table. Example: {'status': 'Cancelled', 'remarks': 'Cancelled per customer request'}."

addedInput schema / properties / data / minProperties
```
Added value: +1
```

changedInput schema / properties / doctype / description

Previous value: -"The DocType of the document to update (e.g. 'Sales Invoice', 'Customer', 'Item', 'Sales Order'). Must match the doctype of the existing document."New value: +"The DocType of the document to update (e.g. 'Sales Invoice', 'Customer', 'Item', 'Sales Order'). Case-sensitive and must match the doctype of the existing document."

addedInput schema / properties / doctype / minLength
```
Added value: +1
```

changedInput schema / properties / name / description

Previous value: -"The unique document name or ID of the existing document to modify (e.g. 'SINV-00001', 'CUST-00001', 'ITEM-00001')."New value: +"The `name` primary key of the existing document to modify (e.g. 'SINV-00001', 'CUST-00001', 'ITEM-00001'). The document must already exist; this tool does not create one."

addedInput schema / properties / name / minLength
```
Added value: +1
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "data": {
+      "additionalProperties": true,
+      "description": "A Frappe document. Keys are DocType fieldnames; child tables appear as arrays of row objects. Always includes `name` (the primary key), `owner`, `creation`, `modified` and `docstatus` (0 = draft, 1 = submitted, 2 = cancelled).",
+      "type": "object"
+    }
+  },
+  "required": [
+    "data"
+  ],
+  "type": "object"
+}

Changed6 schema fields changedv1.1.0Jul 29, 2026

changedInput schema / properties / data / description

Previous value: -"Key-value pairs of fields to update."New value: +"Dictionary of field names and their new values. Only the fields included here are modified; other fields retain their current values. Example: {'status': 'Cancelled', 'remarks': 'Cancelled per customer request'}."

addedInput schema / properties / data / examples

Added value: +[
+  {
+    "remarks": "Cancelled per customer request",
+    "status": "Cancelled"
+  },
+  {
+    "email_id": "newemail@example.com",
+    "mobile_no": "+1234567890"
+  }
+]

changedInput schema / properties / doctype / description

Previous value: -"The DocType of the document."New value: +"The DocType of the document to update (e.g. 'Sales Invoice', 'Customer', 'Item', 'Sales Order'). Must match the doctype of the existing document."

addedInput schema / properties / doctype / examples

Added value: +[
+  "Sales Invoice",
+  "Customer",
+  "Item"
+]

changedInput schema / properties / name / description

Previous value: -"The document name/ID."New value: +"The unique document name or ID of the existing document to modify (e.g. 'SINV-00001', 'CUST-00001', 'ITEM-00001')."

addedInput schema / properties / name / examples

Added value: +[
+  "SINV-00001",
+  "CUST-00001"
+]

First observedv1.0.0Jul 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only flag write/destructive/idempotent/openWorld; the description adds far more: overwritten values are unrecoverable through this API, DocType validation hooks run and the save is all-or-nothing, submitted documents (docstatus 1) reject edits to fields not marked 'Allow on Submit', and write permission on the DocType is required. This is exactly the behavioural context annotations cannot express.

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

Conciseness4/5

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

Front-loaded with purpose and routing, then cleanly sectioned into Behavior, Parameters and Returns. It is on the long side and the Returns line partly duplicates the output schema, but nearly every sentence carries actionable information.

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 destructive nested-object write tool, the definition covers atomicity, submitted-document constraints, permissions, child-table replacement and field clearing. Nothing an agent needs in order to call it safely is missing, even though the redundant Returns clause could be dropped since an output schema exists.

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 coverage is already 100%, so baseline is 3, but the description adds genuinely new semantics: `data` keys are fieldnames not form labels, child-table fields replace the whole table (with a read-then-resend-rows remedy), and fields can only be cleared by explicitly passing null or an empty string. These go beyond the schema text rather than restating it.

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?

Opens with a specific verb+resource+scope: 'Update selected fields of an existing document, identified by its doctype and name.' It immediately distinguishes partial edit semantics from creation and deletion, so an agent can route correctly without opening the schema.

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?

Explicitly names alternatives and the conditions that select them: frappe_create_doc for records that don't exist, and this tool over frappe_delete_doc when a document should be voided while preserving the audit trail. Both the when-to-use and the when-to-prefer-a-different-tool cases are stated.

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

Deploy Server