Fileaify

submit_changes

Propose changes to up to 20 existing documents in one proposal. Each item has document_id, base_revision from read_document, either full content or exact old/new edits, and the sections it changes with their hash from read_document; contract_version comes from read_contract. A change outside the declared sections, a new section or a text over max_chars is refused with the size of each section. Reports go in rationale and evidence. Requires rationale, evidence and idempotency_key. Human review or the project's automatic publication policy applies; a contributor never approves its own change. Returns the change id and status.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>",
      "contract_version": "<contract_version>",
      "rationale": "<rationale>",
      "evidence": "<evidence>",
      "items": "<items>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "submit_changes"
  }
}

Input Schema

Name	Required	Description	Default
`items`	Yes
`evidence`	Yes
`rationale`	Yes
`project_id`	Yes
`result_offset`	No
`idempotency_key`	Yes
`contract_version`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 4, 2026

changedInput schema / properties / evidence / maxLength
```
Previous value: -6000New value: +20000
```

removedInput schema / properties / items / items / properties / journal

Removed value: -{
-  "description": "What happened, kept apart from the document text. Alone, it records an entry without changing the text. Write journal://variable in the text and in another entry to cite it (journal://DOC:variable from another document); the server replaces the variable by the number. journal://12 cites an existing entry. An unknown reference is refused.",
-  "items": {
-    "additionalProperties": false,
-    "properties": {
-      "content": {
-        "maxLength": 150000,
-        "minLength": 1,
-        "type": "string"
-      },
-      "variable": {
-        "pattern": "^(?!\\d+$)[\\w-]{1,64}$",
-        "type": "string"
-      }
-    },
-    "required": [
-      "content"
-    ],
-    "type": "object"
-  },
-  "maxItems": 60,
-  "minItems": 1,
-  "type": "array"
-}

addedInput schema / properties / items / items / properties / sections

Added value: +{
+  "description": "Each section this item changes, with the hash returned by read_document. A new template section has no hash. Required unless the document is still at its starting text.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "hash": {
+        "maxLength": 64,
+        "type": "string"
+      },
+      "section": {
+        "maxLength": 400,
+        "type": "string"
+      }
+    },
+    "required": [
+      "section"
+    ],
+    "type": "object"
+  },
+  "maxItems": 60,
+  "minItems": 1,
+  "type": "array"
+}

Changed1 schema field changedNov 4, 2026

addedInput schema / properties / items / items / properties / journal

Added value: +{
+  "description": "What happened, kept apart from the document text. Alone, it records an entry without changing the text. Write journal://variable in the text and in another entry to cite it (journal://DOC:variable from another document); the server replaces the variable by the number. journal://12 cites an existing entry. An unknown reference is refused.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "content": {
+        "maxLength": 150000,
+        "minLength": 1,
+        "type": "string"
+      },
+      "variable": {
+        "pattern": "^(?!\\d+$)[\\w-]{1,64}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "content"
+    ],
+    "type": "object"
+  },
+  "maxItems": 60,
+  "minItems": 1,
+  "type": "array"
+}

First observedNov 3, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Annotations only declare the safety profile (not read-only, not destructive), while the description adds real behavior: rejection rules for out-of-scope sections, new sections and oversized text, with section sizes returned. It also discloses the governance model (human review or automatic publication policy, no self-approval) and the return value (change id and status). The required idempotency_key sits slightly oddly next to idempotentHint=false, but the description itself makes no idempotency claim, so this is not a contradiction.

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 the action and batch limit, then prerequisites, then failure modes, then governance and return value. The mid-section sentence is semicolon-chained and dense, but no sentence is filler.

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

Completeness4/5

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

For a 7-parameter batch mutation with nested items and no output schema, this covers the essential contract: revision pinning, section hashes, size limits, refusal behavior and review outcome. The gaps are project_id, result_offset/pagination, and how a partially refused batch is reported.

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 0%, so the description carries the burden and does so for most fields: document_id, base_revision, sections/hash provenance, contract_version, rationale, evidence and idempotency_key all get meaning. project_id and result_offset are never mentioned, leaving two fields undocumented anywhere.

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

Purpose4/5

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

The first sentence gives a specific verb (propose), resource (changes to existing documents) and a hard scope limit (up to 20 documents in one proposal). It is clearly distinct from create_document and restore_document by naming existing documents and revisions. It never explicitly names the nearest sibling, amend_changes, so the differentiation is inferred rather than stated.

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

Usage Guidelines4/5

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

Prerequisites are spelled out concretely: base_revision and section hashes must come from read_document and contract_version from read_contract. It also states the acceptance conditions (declared sections only, no new sections, within max_chars) and the review path. It stops short of saying when to use this instead of amend_changes or how to proceed after a refusal.

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

All Fileaify tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?