Skip to main content
Glama
Sign In
DocsMint

DocsMint

by HiAi-gg
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

save_document

Destructive

Create a new document or update an existing one by setting its title, Markdown content, folder, category, or workspace; content and placement changes queue normal indexing.

Instructions

Create or update one document. Use action=create for a new document or action=update for an existing one; batch_documents handles the same placement change across multiple existing documents. Creation requires write access; content edits require edit access, and placement changes may require write access. Content or placement changes queue normal indexing.

Input Schema

NameRequiredDescriptionDefault
idNoUUID returned by the corresponding list or read operation.
titleNoDocument title, from 1 to 500 characters.
actionNo
contentNoMarkdown document content; an empty string clears the content on update.
folderIdNo
categoryIdNoOptional category UUID; null clears the explicit category.
workspaceIdNoWorkspace UUID from list_workspace_structure(kind=workspaces). Required for ambiguous creates and structure changes; omit to search all granted scopes.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv2.1.1
    • changedInput schema / properties / categoryId / anyOf
      Previous value: -[
-  {
-    "anyOf": [
-      {
-        "description": "UUID returned by the corresponding list or read operation.",
-        "format": "uuid",
-        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-        "type": "string"
-      },
-      {
-        "type": "null"
-      }
-    ],
-    "description": "Optional category UUID; null clears the explicit category."
-  },
-  {
-    "anyOf": [
-      {
-        "description": "UUID returned by the corresponding list or read operation.",
-        "format": "uuid",
-        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-        "type": "string"
-      },
-      {
-        "type": "null"
-      }
-    ],
-    "description": "Optional category UUID; null clears the explicit category."
-  }
-]New value: +[
+  {
+    "description": "UUID returned by the corresponding list or read operation.",
+    "format": "uuid",
+    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / categoryId / description
      Added value: +"Optional category UUID; null clears the explicit category."
    • removedInput schema / properties / content / anyOf
      Removed value: -[
-  {
-    "description": "Markdown document content; an empty string clears the content on update.",
-    "type": "string"
-  },
-  {
-    "description": "Markdown document content; an empty string clears the content on update.",
-    "type": "string"
-  }
-]
    • addedInput schema / properties / content / description
      Added value: +"Markdown document content; an empty string clears the content on update."
    • addedInput schema / properties / content / type
      Added value: +"string"
    • removedInput schema / properties / title / anyOf
      Removed value: -[
-  {
-    "description": "Document title, from 1 to 500 characters.",
-    "maxLength": 500,
-    "minLength": 1,
-    "type": "string"
-  },
-  {
-    "description": "Document title, from 1 to 500 characters.",
-    "maxLength": 500,
-    "minLength": 1,
-    "type": "string"
-  }
-]
    • addedInput schema / properties / title / description
      Added value: +"Document title, from 1 to 500 characters."
    • addedInput schema / properties / title / maxLength
      Added value: +500
    • addedInput schema / properties / title / minLength
      Added value: +1
    • addedInput schema / properties / title / type
      Added value: +"string"
  2. Changed3 schema fields changedv2.0.4
    • changedInput schema / oneOf
      Previous value: -[
-  {
-    "allOf": [
-      {
-        "not": {
-          "anyOf": [
-            {
-              "required": [
-                "id"
-              ]
-            }
-          ]
-        }
-      }
-    ],
-    "properties": {
-      "action": {
-        "const": "create",
-        "description": "Select the create operation explicitly.",
-        "type": "string"
-      },
-      "categoryId": {
-        "anyOf": [
-          {
-            "description": "UUID returned by the corresponding list or read operation.",
-            "format": "uuid",
-            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Optional category UUID; null clears the explicit category."
-      },
-      "content": {
-        "description": "Markdown document content; an empty string clears the content on update.",
-        "type": "string"
-      },
-      "folderId": {
-        "description": "UUID returned by the corresponding list or read operation.",
-        "format": "uuid",
-        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-        "type": "string"
-      },
-      "title": {
-        "description": "Document title, from 1 to 500 characters.",
-        "maxLength": 500,
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "action"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "action": {
-        "const": "update",
-        "description": "Select the update operation explicitly.",
-        "type": "string"
-      },
-      "categoryId": {
-        "anyOf": [
-          {
-            "description": "UUID returned by the corresponding list or read operation.",
-            "format": "uuid",
-            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Optional category UUID; null clears the explicit category."
-      },
-      "content": {
-        "description": "Markdown document content; an empty string clears the content on update.",
-        "type": "string"
-      },
-      "folderId": {
-        "anyOf": [
-          {
-            "description": "UUID returned by the corresponding list or read operation.",
-            "format": "uuid",
-            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Optional folder UUID; null clears the placement on update."
-      },
-      "id": {
-        "description": "UUID returned by the corresponding list or read operation.",
-        "format": "uuid",
-        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-        "type": "string"
-      },
-      "title": {
-        "description": "Document title, from 1 to 500 characters.",
-        "maxLength": 500,
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "action",
-      "id"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "allOf": [
+      {
+        "not": {
+          "anyOf": [
+            {
+              "required": [
+                "id"
+              ]
+            }
+          ]
+        }
+      }
+    ],
+    "properties": {
+      "action": {
+        "const": "create",
+        "description": "Select the create operation explicitly.",
+        "type": "string"
+      },
+      "categoryId": {
+        "anyOf": [
+          {
+            "description": "UUID returned by the corresponding list or read operation.",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Optional category UUID; null clears the explicit category."
+      },
+      "content": {
+        "description": "Markdown document content; an empty string clears the content on update.",
+        "type": "string"
+      },
+      "folderId": {
+        "description": "UUID returned by the corresponding list or read operation.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      },
+      "title": {
+        "description": "Document title, from 1 to 500 characters.",
+        "maxLength": 500,
+        "minLength": 1,
+        "type": "string"
+      },
+      "workspaceId": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "description": "Workspace UUID from list_workspace_structure(kind=workspaces). Required for ambiguous creates and structure changes; omit to search all granted scopes.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "action"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "action": {
+        "const": "update",
+        "description": "Select the update operation explicitly.",
+        "type": "string"
+      },
+      "categoryId": {
+        "anyOf": [
+          {
+            "description": "UUID returned by the corresponding list or read operation.",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Optional category UUID; null clears the explicit category."
+      },
+      "content": {
+        "description": "Markdown document content; an empty string clears the content on update.",
+        "type": "string"
+      },
+      "folderId": {
+        "anyOf": [
+          {
+            "description": "UUID returned by the corresponding list or read operation.",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Optional folder UUID; null clears the placement on update."
+      },
+      "id": {
+        "description": "UUID returned by the corresponding list or read operation.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      },
+      "title": {
+        "description": "Document title, from 1 to 500 characters.",
+        "maxLength": 500,
+        "minLength": 1,
+        "type": "string"
+      },
+      "workspaceId": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "description": "Workspace UUID from list_workspace_structure(kind=workspaces). Required for ambiguous creates and structure changes; omit to search all granted scopes.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "action",
+      "id"
+    ],
+    "type": "object"
+  }
+]
    • addedInput schema / properties / workspaceId
      Added value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "Workspace UUID from list_workspace_structure(kind=workspaces). Required for ambiguous creates and structure changes; omit to search all granted scopes.",
+  "format": "uuid",
+  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+  "type": "string"
+}
    • changedOutput schema / anyOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "operation": {
-        "const": "create",
-        "type": "string"
-      },
-      "result": {
-        "additionalProperties": {},
-        "properties": {
-          "categoryId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "content": {
-            "type": "string"
-          },
-          "contentJson": {},
-          "createdAt": {
-            "type": "string"
-          },
-          "folderId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "folderName": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "id": {
-            "type": "string"
-          },
-          "metadata": {},
-          "ownerId": {
-            "type": "string"
-          },
-          "tags": {
-            "items": {
-              "additionalProperties": {},
-              "properties": {
-                "color": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ]
-                },
-                "createdAt": {
-                  "type": "string"
-                },
-                "documentCount": {
-                  "type": "number"
-                },
-                "id": {
-                  "type": "string"
-                },
-                "name": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "id",
-                "name",
-                "color"
-              ],
-              "type": "object"
-            },
-            "type": "array"
-          },
-          "title": {
-            "type": "string"
-          },
-          "updatedAt": {
-            "type": "string"
-          },
-          "visibility": {
-            "enum": [
-              "private",
-              "shared",
-              "public"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "ownerId",
-          "folderId",
-          "categoryId",
-          "title",
-          "content",
-          "visibility",
-          "createdAt",
-          "updatedAt"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "operation",
-      "result"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "operation": {
-        "const": "update",
-        "type": "string"
-      },
-      "result": {
-        "additionalProperties": {},
-        "properties": {
-          "categoryId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "content": {
-            "type": "string"
-          },
-          "contentJson": {},
-          "createdAt": {
-            "type": "string"
-          },
-          "folderId": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "folderName": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "id": {
-            "type": "string"
-          },
-          "metadata": {},
-          "ownerId": {
-            "type": "string"
-          },
-          "tags": {
-            "items": {
-              "additionalProperties": {},
-              "properties": {
-                "color": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "null"
-                    }
-                  ]
-                },
-                "createdAt": {
-                  "type": "string"
-                },
-                "documentCount": {
-                  "type": "number"
-                },
-                "id": {
-                  "type": "string"
-                },
-                "name": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "id",
-                "name",
-                "color"
-              ],
-              "type": "object"
-            },
-            "type": "array"
-          },
-          "title": {
-            "type": "string"
-          },
-          "updatedAt": {
-            "type": "string"
-          },
-          "visibility": {
-            "enum": [
-              "private",
-              "shared",
-              "public"
-            ],
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "ownerId",
-          "folderId",
-          "categoryId",
-          "title",
-          "content",
-          "visibility",
-          "createdAt",
-          "updatedAt"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "operation",
-      "result"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "operation": {
+        "const": "create",
+        "type": "string"
+      },
+      "result": {
+        "additionalProperties": {},
+        "properties": {
+          "categoryId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "content": {
+            "type": "string"
+          },
+          "contentJson": {},
+          "createdAt": {
+            "type": "string"
+          },
+          "folderId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "folderName": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "type": "string"
+          },
+          "metadata": {},
+          "ownerId": {
+            "type": "string"
+          },
+          "tags": {
+            "items": {
+              "additionalProperties": {},
+              "properties": {
+                "color": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "createdAt": {
+                  "type": "string"
+                },
+                "documentCount": {
+                  "type": "number"
+                },
+                "id": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "name",
+                "color"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "title": {
+            "type": "string"
+          },
+          "updatedAt": {
+            "type": "string"
+          },
+          "visibility": {
+            "enum": [
+              "private",
+              "shared",
+              "public"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "ownerId",
+          "folderId",
+          "categoryId",
+          "title",
+          "content",
+          "visibility",
+          "createdAt",
+          "updatedAt"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "operation",
+      "result"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "operation": {
+        "const": "update",
+        "type": "string"
+      },
+      "result": {
+        "additionalProperties": {},
+        "properties": {
+          "categoryId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "content": {
+            "type": "string"
+          },
+          "contentJson": {},
+          "createdAt": {
+            "type": "string"
+          },
+          "folderId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "folderName": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "type": "string"
+          },
+          "metadata": {},
+          "ownerId": {
+            "type": "string"
+          },
+          "tags": {
+            "items": {
+              "additionalProperties": {},
+              "properties": {
+                "color": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "createdAt": {
+                  "type": "string"
+                },
+                "documentCount": {
+                  "type": "number"
+                },
+                "id": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "name",
+                "color"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "title": {
+            "type": "string"
+          },
+          "updatedAt": {
+            "type": "string"
+          },
+          "visibility": {
+            "enum": [
+              "private",
+              "shared",
+              "public"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "ownerId",
+          "folderId",
+          "categoryId",
+          "title",
+          "content",
+          "visibility",
+          "createdAt",
+          "updatedAt"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "operation",
+      "result"
+    ],
+    "type": "object"
+  }
+]
  3. Changed3 schema fields changedv1.0.3
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / oneOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "const": "create",
-        "description": "Select the create operation explicitly.",
-        "type": "string"
-      },
-      "categoryId": {
-        "anyOf": [
-          {
-            "description": "UUID returned by the corresponding list or read operation.",
-            "format": "uuid",
-            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Optional category UUID; null clears the explicit category."
-      },
-      "content": {
-        "description": "Markdown document content; an empty string clears the content on update.",
-        "type": "string"
-      },
-      "folderId": {
-        "description": "UUID returned by the corresponding list or read operation.",
-        "format": "uuid",
-        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-        "type": "string"
-      },
-      "title": {
-        "description": "Document title, from 1 to 500 characters.",
-        "maxLength": 500,
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "action"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "const": "update",
-        "description": "Select the update operation explicitly.",
-        "type": "string"
-      },
-      "categoryId": {
-        "anyOf": [
-          {
-            "description": "UUID returned by the corresponding list or read operation.",
-            "format": "uuid",
-            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Optional category UUID; null clears the explicit category."
-      },
-      "content": {
-        "description": "Markdown document content; an empty string clears the content on update.",
-        "type": "string"
-      },
-      "folderId": {
-        "anyOf": [
-          {
-            "description": "UUID returned by the corresponding list or read operation.",
-            "format": "uuid",
-            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "description": "Optional folder UUID; null clears the placement on update."
-      },
-      "id": {
-        "description": "UUID returned by the corresponding list or read operation.",
-        "format": "uuid",
-        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
-        "type": "string"
-      },
-      "title": {
-        "description": "Document title, from 1 to 500 characters.",
-        "maxLength": 500,
-        "minLength": 1,
-        "type": "string"
-      }
-    },
-    "required": [
-      "action",
-      "id"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "allOf": [
+      {
+        "not": {
+          "anyOf": [
+            {
+              "required": [
+                "id"
+              ]
+            }
+          ]
+        }
+      }
+    ],
+    "properties": {
+      "action": {
+        "const": "create",
+        "description": "Select the create operation explicitly.",
+        "type": "string"
+      },
+      "categoryId": {
+        "anyOf": [
+          {
+            "description": "UUID returned by the corresponding list or read operation.",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Optional category UUID; null clears the explicit category."
+      },
+      "content": {
+        "description": "Markdown document content; an empty string clears the content on update.",
+        "type": "string"
+      },
+      "folderId": {
+        "description": "UUID returned by the corresponding list or read operation.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      },
+      "title": {
+        "description": "Document title, from 1 to 500 characters.",
+        "maxLength": 500,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "action"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "action": {
+        "const": "update",
+        "description": "Select the update operation explicitly.",
+        "type": "string"
+      },
+      "categoryId": {
+        "anyOf": [
+          {
+            "description": "UUID returned by the corresponding list or read operation.",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Optional category UUID; null clears the explicit category."
+      },
+      "content": {
+        "description": "Markdown document content; an empty string clears the content on update.",
+        "type": "string"
+      },
+      "folderId": {
+        "anyOf": [
+          {
+            "description": "UUID returned by the corresponding list or read operation.",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Optional folder UUID; null clears the placement on update."
+      },
+      "id": {
+        "description": "UUID returned by the corresponding list or read operation.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      },
+      "title": {
+        "description": "Document title, from 1 to 500 characters.",
+        "maxLength": 500,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "action",
+      "id"
+    ],
+    "type": "object"
+  }
+]
    • addedInput schema / properties
      Added value: +{
+  "action": {
+    "anyOf": [
+      {
+        "const": "create",
+        "description": "Select the create operation explicitly.",
+        "type": "string"
+      },
+      {
+        "const": "update",
+        "description": "Select the update operation explicitly.",
+        "type": "string"
+      }
+    ]
+  },
+  "categoryId": {
+    "anyOf": [
+      {
+        "anyOf": [
+          {
+            "description": "UUID returned by the corresponding list or read operation.",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Optional category UUID; null clears the explicit category."
+      },
+      {
+        "anyOf": [
+          {
+            "description": "UUID returned by the corresponding list or read operation.",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Optional category UUID; null clears the explicit category."
+      }
+    ]
+  },
+  "content": {
+    "anyOf": [
+      {
+        "description": "Markdown document content; an empty string clears the content on update.",
+        "type": "string"
+      },
+      {
+        "description": "Markdown document content; an empty string clears the content on update.",
+        "type": "string"
+      }
+    ]
+  },
+  "folderId": {
+    "anyOf": [
+      {
+        "description": "UUID returned by the corresponding list or read operation.",
+        "format": "uuid",
+        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+        "type": "string"
+      },
+      {
+        "anyOf": [
+          {
+            "description": "UUID returned by the corresponding list or read operation.",
+            "format": "uuid",
+            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Optional folder UUID; null clears the placement on update."
+      }
+    ]
+  },
+  "id": {
+    "description": "UUID returned by the corresponding list or read operation.",
+    "format": "uuid",
+    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+    "type": "string"
+  },
+  "title": {
+    "anyOf": [
+      {
+        "description": "Document title, from 1 to 500 characters.",
+        "maxLength": 500,
+        "minLength": 1,
+        "type": "string"
+      },
+      {
+        "description": "Document title, from 1 to 500 characters.",
+        "maxLength": 500,
+        "minLength": 1,
+        "type": "string"
+      }
+    ]
+  }
+}
  4. Addedv0.1.2

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare this as a destructive, non-idempotent mutation, so the description benefits from adding permission requirements and side effects. It adds that creation needs write access, content edits need edit access, placement changes may need write access, and content or placement changes queue indexing.

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 three compact sentences and front-loads the core create/update behavior. Every sentence contributes actionable routing, permission, or side-effect 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?

Given the oneOf schema, annotations, and output schema, the description supplies the key decision context: create vs update, batch alternative, permissions, and indexing consequences. An agent has enough information to choose and invoke the tool correctly.

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

Parameters3/5

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

Schema description coverage is 71%, so most parameter meaning is already supplied by the schema. The description clarifies that action=create means new document and action=update means existing document, but it does not add much beyond the schema for the remaining parameters.

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 states a specific verb and resource: create or update one document. It also distinguishes the tool from batch_documents, which handles placement changes across multiple existing documents.

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 explicitly says action=create is for a new document and action=update is for an existing one. It names batch_documents as the alternative for multi-document placement changes and states the access-level prerequisites.

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

Deploy Server

Other Tools