Skip to main content
Glama

AILANG Parse

by io.github.sunholo-data
OverviewDiscussionsAdmin

Edit document

editDocument
Read-only

Edit a document: parse it, apply a JSON array of edit deltas, and return the modified blocks (same shape as mcpParse with outputFormat "blocks"). deltas "" or "[]" returns the document unchanged. Office formats only: docx, pptx, xlsx, odt, odp, ods. Give the document ONE way: fileRef: a file the user uploaded (mcp-file://docparse/file_...). file: in ChatGPT, the file the user attached (ChatGPT fills it in). content + filename: the file base64-encoded, contentEncoding="base64", e.g. filename "contract.docx". filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". To get a file back, pass the edited blocks' Markdown to mcpConvert. Which way to send a file: a file in your sandbox or workspace: call createUpload (one token PER FILE; set count for several) and run its curl line, then pass the fileRef here. curl fails with a network error, or the user wants to pick a file: call uploadDocument (the user chooses it in the AILANG Parse card). The card parses the file; it does not convert or edit it. a public https:// link; short text as content. In ChatGPT, file. Never parse the file yourself (your own script, or your own reading of it) and present that as this tool's result: if the file cannot be sent, tell the user.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fileNo
apiKeyNo
deltasNo
contentNo
fileRefNo
filenameNo
filepathNo
contentEncodingNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / file
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "download_url": {
+      "type": "string"
+    },
+    "file_id": {
+      "type": "string"
+    },
+    "file_name": {
+      "type": "string"
+    },
+    "mime_type": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "download_url",
+    "file_id"
+  ],
+  "type": "object"
+}
    • addedInput schema / properties / fileRef
      Added value: +{
+  "type": "string"
+}
  2. Changed4 schema fields changed
    • addedInput schema / properties / content
      Added value: +{
+  "type": "string"
+}
    • addedInput schema / properties / contentEncoding
      Added value: +{
+  "type": "string"
+}
    • addedInput schema / properties / filename
      Added value: +{
+  "type": "string"
+}
    • changedInput schema / required
      Previous value: -[
-  "filepath",
-  "deltas"
-]New value: +[]
  3. Changed1 schema field changed
    • changedInput schema / required
      Previous value: -[
-  "filepath",
-  "deltas",
-  "apiKey"
-]New value: +[
+  "filepath",
+  "deltas"
+]
  4. Added

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true; the description is consistent with this (it returns blocks rather than persisting edits, and tells you to convert them yourself). It adds real context beyond the annotations: the 'deltas "" or "[]" returns unchanged' edge case, the supported office formats, and failure-handling guidance. It does not explain the idempotentHint=false or the apiKey parameter, leaving small gaps.

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?

Purpose and return shape are front-loaded, and the two bulleted lists make the file-input options scannable. It is longer than typical, with some overlap between 'Give the document ONE way' and 'Which way to send a file', but the duplication serves distinct purposes (parameter format vs. routing) and the length is justified by the tool's complexity.

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?

With no output schema, the description still conveys the return value ('same shape as mcpParse with outputFormat "blocks"') and the unchanged-document edge case. Supported formats and input routes are covered; only the apiKey requirement and the reason for non-idempotency are unaddressed, which are minor for an agent calling this tool.

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 0% and there are 8 parameters, so the description must carry the burden, and it largely does: it explains fileRef, file, content+filename, contentEncoding,"base64", filepath (https URL or sample id), and deltas. Only apiKey is left undocumented, so it compensates well for the coverage gap without being exhaustive.

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 specific verb+resource and full behavior chain: 'Edit a document: parse it, apply a JSON array of edit deltas, and return the modified blocks.' It also anchors the return shape to a named sibling ('same shape as mcpParse with outputFormat "blocks"'), so an agent can distinguish it from mcpParse/mcpConvert without reading any 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?

It gives explicit routing rules: use createUpload (one token per file) for sandbox files, uploadDocument when curl fails or the user must pick a file, and filepath/content/ChatGPT file for other cases. It even names when-not ('Never parse the file yourself') and the destination for follow-up work ('pass the edited blocks' Markdown to mcpConvert').

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

All AILANG Parse toolsInspect
Try in Browser
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources