Deterministic DOCX/PPTX/XLSX/PDF parser: track changes, comments, headers, footers, merged cells.
Scored across 12 tools
The three upload tools (createUpload, uploadDocument, uploadViaHost) all concern getting a file in, and mcpParse vs mcpConvert overlap conceptually. The descriptions do distinguish them (sandbox tokens vs user-picked file vs internal widget relay), but an agent must read carefully to route correctly.
Three conventions coexist: mcp-prefixed tools (mcpParse, mcpConvert, mcpAuth), camelCase verb tools (createUpload, editDocument, uploadDocument), and one snake_case tool (submit_feedback). There is a loose grouping logic but it is not a single predictable pattern.
12 tools is well within the reasonable range for a document parse/convert/edit service. Each tool covers a distinct capability (parse, convert, edit, formats, estimate, account, auth, upload, feedback) with little redundancy.
The surface covers the full parse/convert/edit lifecycle plus formats, cost estimation, auth, and account management. Minor gaps like batch multi-file parse or explicit delete/history-management operations exist, but core workflows are covered.
Get one-time upload links for files in your sandbox or workspace, when you can run shell commands with network access (Claude Code, Codex, a code sandbox). One token PER FILE: a token uploads exactly one file. For several files set count (1..20) to get that many descriptors in one call. Each descriptor has a curl line: run it where the file is (replace ); it prints a receipt with a fileRef. Then call mcpParse, mcpConvert or editDocument with that fileRef. Tokens work once, for 10 minutes. If curl fails with a network error, or the user wants to pick a file, call uploadDocument instead, or ask for an https:// link. Never parse the file yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| apiKey | No | ||
| filename | No | ||
| mimeType | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations (which only mark it non-read-only, open-world, non-idempotent, non-destructive) by disclosing that tokens are single-use, expire in 10 minutes, that one token maps to exactly one file, the 1..20 count scaling, and the required curl/receipt/fileRef workflow. It even handles the failure mode, which 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and workflow, and every sentence carries real information (expiry, count, receipt, fallback). It is dense and slightly run-on in the middle, but no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 describes the return shape (descriptors containing a curl line and a receipt with fileRef) and the full call chain. The remaining gap is that three of four inputs and any auth expectations are undocumented, which is significant for a tool whose schema coverage is 0%.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry all four parameters. It explains count well (one descriptor per file, range 1..20) but leaves apiKey, filename, and mimeType completely undefined in both schema and description, including whether apiKey is auth or an override.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource (get one-time upload links for files) plus the execution environment it is built for (shell with network access). It contrasts itself with uploadDocument explicitly, so an agent can distinguish it from siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit use conditions (you can run shell commands with network access) and explicit fallbacks (curl network error or user wants to pick a file -> uploadDocument, or ask for an https:// link). It also names the downstream tools to call with the resulting fileRef, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| apiKey | No | ||
| deltas | No | ||
| content | No | ||
| fileRef | No | ||
| filename | No | ||
| filepath | No | ||
| contentEncoding | No |
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.
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.
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.
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.
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.
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.
Your AILANG Parse account: plan, monthly usage and limits, your keys, and whether request history is kept. Actions: "status" (default) → plan, usage this month and remaining allowance "keys" → your keys with per-key usage ("usage" is an alias) "history" → whether request history (parsed output kept for replay) is on for your account "history_on" / "history_off" → change it for the account and all its keys
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | ||
| apiKey | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and idempotentHint=true, and the description is consistent with that while adding real context the annotations don't carry: history_on/history_off mutate the account and ALL its keys, not just one. It omits auth requirements, rate limits, and any caution that history toggles are account-wide writes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the resource definition, then a clean action-to-behavior mapping with the default called out — efficient and scannable. Minor formatting noise (stray quote/indentation in the action list) keeps it from being flawless.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an action-dispatch tool with no output schema and only generic annotations, the description covers the actions and the account-wide mutation scope adequately. The main omissions are the role of apiKey and whether history toggles are reversible, plus expected return shape for each action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for both parameters. It does so well for 'action' (enumerates all legal values and the default) but says nothing about 'apiKey' or whether it is needed, leaving half the parameter surface undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (the AILANG Parse account) and enumerates the concrete things it covers: plan, monthly usage, limits, keys, and request-history settings. An agent can tell this apart from mcpAuth/mcpParse siblings at a glance, since it is unambiguously the account/quota tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Each action is listed with its purpose and the default ('status' is marked default), so the agent knows how to select behavior. It stops short of naming when to prefer a sibling tool or when-not to use this one, so it is clear context without explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start device authorization to get an API key. Returns device_code, user_code, and verification URL. The agent should display the verification URL to the user, who signs in and approves the code. Then call mcpAuthPoll with the device_code. MCP wrappers don't have HTTP request headers, so provenance is empty here.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as non-read-only, open-world, non-idempotent; the description goes beyond them by disclosing the return payload (device_code, user_code, verification URL), the required user action, the follow-up call, and the unusual note that provenance is empty because MCP wrappers lack HTTP headers. Missing details on code expiration or rate limits keep it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and return values are front-loaded, and each sentence carries actionable information (display URL, poll next, provenance note). The provenance sentence is tangential to invoking the tool but is short and harmless.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description responsibly enumerates the returned fields and the endpoint handoff to mcpAuthPoll, giving the agent enough to drive the flow. The unresolved 'label' parameter and absence of expiration/error handling are the only gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and there is one required parameter, 'label', whose meaning, format, or purpose is never explained in the description. The description must compensate for the undocumented parameter and does not, leaving the agent to guess what value to supply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and outcome ('Start device authorization to get an API key') and names the exact next sibling (mcpAuthPoll), so an agent can distinguish this initiation step from the polling step and from mcpAccount without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit usage: display the verification URL to the user, wait for approval, then call mcpAuthPoll with the device_code. This is a complete when-to-use and what-to-do-next instruction naming the alternative sibling. The only omission is a 'when not to use' (e.g. if an API key already exists), which is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll for device authorization completion. Returns "pending" (keep polling every 5s), "approved" (with api_key and tier), or "expired" (start over with mcpAuth).
| Name | Required | Description | Default |
|---|---|---|---|
| deviceCode | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the 5s polling cadence and the three terminal statuses with their follow-up actions. It does not state auth/prerequisite details for the deviceCode itself, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the action and then the return semantics. No filler; every clause conveys an actionable state or instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description carries the essential information an agent needs, including the return states and retry/restart rules. Only the origin and format of deviceCode is left implicit, a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one required parameter (deviceCode) at 0% schema description coverage, so the schema gives no meaning. The description implies the device authorization context and that deviceCode originates from the mcpAuth flow, but never names or explains the parameter, so it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (poll) and resource (device authorization completion) and enumerates the exact return states ('pending', 'approved', 'expired'). It also explicitly distinguishes itself from the mcpAuth sibling as the restart path, so an agent can select it without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use behavior: keep polling every 5s on 'pending', start over with mcpAuth on 'expired'. The alternative tool is named along with the condition that routes to it, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a document in another format: docx, pptx, xlsx, odt, odp, ods, html, md or qmd. To write a new document, write Markdown and send it as content with filename "notes.md" (headings become slides in pptx). To convert an existing document, give it 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 document itself; binary files base64-encoded with contentEncoding="base64", text as plain text. input: an https:// URL of a publicly reachable document, or a sample id from mcpFormats. 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. The result carries download_url, a link to the generated file valid for one hour: give it to the user. It also carries the file as base64 in content (encoding "base64"; text formats come back as utf8).
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| input | No | ||
| apiKey | No | ||
| content | No | ||
| fileRef | No | ||
| filename | No | ||
| outputPath | No | ||
| outputFormat | Yes | ||
| contentEncoding | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that download_url expires after one hour, that the result is also returned as base64/utf8 content, that createUpload issues one token per file, and that the card parses but does not convert. It also warns against a specific failure mode (parsing the file yourself and presenting that as the tool's result).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core purpose and then uses structured, scannable branches; nearly every sentence carries actionable guidance. It is dense and long, but the length is driven by genuine routing complexity rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter conversion tool with no output schema, the description covers input channels and return values well (download_url plus base64/utf8 content). Auth (apiKey) and outputPath are never addressed, so it is not quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage the description must carry the load, and it does explain fileRef, file, content+filename, contentEncoding='base64', input and the outputFormat values. It leaves apiKey and outputPath unexplained, which is the only real gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a document in another format') and immediately enumerates the supported target formats. It is clearly distinguishable from siblings like createUpload, uploadDocument and mcpFormats, which it explicitly routes to by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit decision tree for the four input channels (fileRef, file, content+filename, input) and a 'which way to send a file' branch covering sandbox files, curl failures, user-picked files and public URLs. It also names the fallback tools (createUpload, uploadDocument) and the conditions that select them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate cost and latency for parsing a document. Accepts a file path or sample_id. No auth required.
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | ||
| outputFormat | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful 'No auth required' fact and that a sample_id is accepted, but the sample_id claim conflicts with the schema, which exposes only filepath and outputFormat.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the estimate scope followed by input/auth facts. Minimal waste, though the nonexistent sample_id reference is a small structural flaw.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With two required parameters at 0% schema coverage and no output schema, the description should at least explain what the returned estimate looks like and what outputFormat controls. It omits the required outputFormat entirely and misdescribes the input options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the burden. It mentions only 'file path' (mapping to the filepath param) and a 'sample_id' that does not exist in the schema, while never explaining the required outputFormat parameter or its accepted values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Estimate') and resources ('cost and latency') scoped to 'parsing a document', which clearly separates it from the mcpParse sibling. It stops short of explicitly naming that sibling or explaining how the estimate relates to the actual parse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The implied use case (estimate before parsing) is inferable, and 'No auth required' gives a precondition. However there is no explicit when-to-use versus alternatives, no statement of when to prefer this over mcpParse or mcpConvert, and no guidance on required inputs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What AILANG Parse can read and write, how to send it a document, and the sample documents you can try without one. No sign-in needed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/non-destructive/openWorld=false, so the bar is lower. The description adds auth context not present in annotations ('No sign-in needed') and previews the response content (formats, submission method, sample documents), which is useful behavioral disclosure beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that wastes no words and leads with the core offering. It packs three items slightly densely but remains readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero params, no output schema, and annotations covering the safety profile, the description adequately conveys purpose, auth requirement, and rough return content for a simple read-only discovery tool. Minor gap: no explicit routing to operational siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so per the rubric the baseline is 4. There is no parameter surface for the description to clarify or omit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific purpose: it enumerates what AILANG Parse can read/write, how to submit a document, and available samples. It's clearly the discovery/capabilities endpoint, distinguishable in intent from operational siblings like mcpParse or mcpConvert, though it doesn't name any sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (consult this to learn formats and try samples) but there is no explicit 'when to use this vs X' guidance or mention of alternatives such as mcpParse. The 'no sign-in needed' clause hints at a pre-auth discovery context without stating it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse a document into structured blocks, Markdown, HTML or A2UI, or a short summary of it. Give the document ONE way: fileRef: an uploaded file (mcp-file://docparse/file_...). The same user can use it again for 30 minutes after the first use (more parts, another format), then it is deleted. file: in ChatGPT, the file the user attached (ChatGPT fills it in). filepath: an https:// URL of a publicly reachable document, or a sample id from mcpFormats such as "sample_docx_formatting". content + filename: short text only (Markdown, HTML, CSV); the filename's extension picks the parser. outputFormat: blocks (default), markdown, html, a2ui, or summary (counts, the first 50 headings, warnings: a few KB). Look with summary first when a document may be large. Large documents come in parts: when the result has page.nextCursor, call mcpParse again with the same fileRef/filepath and cursor= for the next part; read every part before answering about the whole document. maxChars sets the part size as a string of digits (default "80000", "2000".."120000"). 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 call this tool with the fileRef the upload prints. 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, which uploads it and gives you its fileRef. a public https:// link: filepath. Short text: content. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| apiKey | No | ||
| cursor | No | ||
| content | No | ||
| fileRef | No | ||
| filename | No | ||
| filepath | No | ||
| maxChars | No | ||
| requestId | No | ||
| outputFormat | No | ||
| contentEncoding | No |
Anonymous bug report / feature request / docs gap, queued for human review. Default routing: public-feedback inbox (general AILANG). Pass package="vendor/name" (e.g. "sunholo/auth") to route to that package's pkg:vendor/name inbox where its autonomous agent watches. Categories: bug, feature, docs, limitation. Body limit 10KB, snippet limit 4KB. Optional contact field for follow-up; opaque to the server. Set auto_dispatch=true to authorize the package agent to act on your submission immediately (default false — files for human triage; pkg-feedback agent template lands in a separate sprint).
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Full description (≤10 KB) | |
| title | Yes | Short title for the report | |
| contact | No | Optional follow-up address (free-form, opaque to the server) | |
| package | No | Optional vendor/name (e.g. "sunholo/auth") to route to that package's pkg:vendor/name inbox. Empty = general AILANG feedback. | |
| snippet | No | Optional code/error snippet (≤4 KB) | |
| category | Yes | bug | feature | docs | limitation | |
| auto_dispatch | No | Authorize the receiving package's autonomous agent to act on this submission. Default false (files for human triage). Tagged on the Pub/Sub notification as category=auto:<original> for coordinator filtering. | |
| ailang_version | Yes | The reporter's CLI version (free-form, used for triage) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (which only flag non-readonly, open-world, non-idempotent, non-destructive) by disclosing size limits (10KB body, 4KB snippet), the human-review queueing behavior, the default routing inbox, the privacy property of `contact` (opaque to server), and what `auto_dispatch=true` authorizes. Rich, non-redundant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose and default routing before the routing variants and limits, with every sentence carrying information. The trailing parenthetical about a 'separate sprint' is mildly extraneous, keeping it just short of a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter submission tool with no output schema but full schema coverage, the description covers routing, categories, size constraints, contact privacy, and the dispatch flag — everything an agent needs to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the default inbox vs. package routing semantics with a concrete example, the enum-like category list, and the default-and-effect of `auto_dispatch`. This meaningfully augments the parameter docs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Anonymous bug report / feature request / docs gap') and its disposition ('queued for human review'), plus the acceptable categories. An agent can tell exactly what this tool submits 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly documents the two routing modes: default `public-feedback` inbox vs. `package="vendor/name"` routing to the `pkg:vendor/name` inbox, and when to set `auto_dispatch=true`. It lacks an explicit 'do not use for X' exclusion, but the routing conditions are clear enough to select correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Let the user pick a file to parse: shows the AILANG Parse card with a Choose file button. The card uploads the file and tries to summarise it for you; either way you get its fileRef. Then call mcpParse with that fileRef for the content (the same user can reuse it for 30 minutes; a large document comes in parts). Use this when the user wants to pick a file, or when createUpload's curl fails with a network error. For a file already in your sandbox or workspace, use createUpload + curl instead. Never parse the file yourself.
| Name | Required | Description | Default |
|---|---|---|---|
| apiKey | No | ||
| outputFormat | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=false, so the safety profile is covered. The description adds real behavioral context beyond that: the fileRef is reusable for 30 minutes, large documents arrive in parts, the card attempts a summary, and the hard guardrail 'Never parse the file yourself.' It does not, however, explain the apiKey requirement or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core flow and the routing rule are front-loaded, and the 'either way you get its fileRef' detail earns its place. It runs slightly long and mixes the UI mechanics with sequencing instructions, but there is little outright filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly explains what you receive (fileRef) and the required follow-up call to mcpParse, plus the 30-minute reuse window. The only notable gap is guidance on the two input parameters, which is absent everywhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for both apiKey and outputFormat, and the description mentions neither parameter, so it does not compensate for the gap. Nothing in the text clarifies their meaning or expected values (e.g. what outputFormat accepts).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (present the AILANG Parse card with a Choose file button, upload the file, return its fileRef) and names the sibling tools it works with (mcpParse, createUpload). An agent can distinguish it from createUpload, uploadViaHost, and mcpParse from the text alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit selection rules: use this when the user wants to pick a file, or when createUpload's curl fails with a network error, and conversely use createUpload + curl for a file already in the sandbox/workspace. When-not conditions and the alternative are both named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Receive a file from the AILANG Parse upload widget, relayed by the host as base64. Only the widget calls this; ticket is the upload token it holds.
| Name | Required | Description | Default |
|---|---|---|---|
| base64 | Yes | ||
| ticket | Yes | ||
| filename | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the write/non-idempotent/open-world/non-destructive profile, so the burden is lower. The description adds the relay mechanism and the fact the ticket is an upload token held by the caller, but says nothing about what happens on success, duplicate/replayed tickets, size limits, or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the action and caller constraint front-loaded. Every clause carries information an agent cannot get from the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an internal widget-facing endpoint with no output schema, the critical fact (agents should not drive this) is stated plainly. It is nearly complete, missing only the success/failure response shape and how the ticket is obtained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for all three required params, so the description must compensate. It explains 'ticket' (the upload token the widget holds) and contextualizes 'base64' as the host-relayed payload, but leaves 'filename' undocumented beyond its self-evident name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (receive) and resource (a file from the AILANG Parse upload widget) and further names the exact transport (base64 relay via host). It also pins the intended caller, which cleanly separates it from siblings like createUpload or mcpParse.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Only the widget calls this" is strong negative routing guidance: an agent reading this should conclude it is not the intended caller. No alternative tool is named for the case where an agent does want to upload, so it stops short of explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
mcpParse2 fields changedInput schema / properties / cursorAdded value: +{
+ "type": "string"
+}Input schema / properties / maxCharsAdded value: +{
+ "type": "string"
+}createUpload1 field changedInput schema / properties / countAdded value: +{
+ "type": "number"
+}uploadDocumentcreateUploadeditDocument2 fields changedInput schema / properties / fileAdded 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"
+}Input schema / properties / fileRefAdded value: +{
+ "type": "string"
+}mcpConvert2 fields changedInput schema / properties / fileAdded 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"
+}Input schema / properties / fileRefAdded value: +{
+ "type": "string"
+}mcpParse2 fields changedInput schema / properties / fileAdded 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"
+}Input schema / properties / fileRefAdded value: +{
+ "type": "string"
+}uploadViaHosteditDocument4 fields changedInput schema / properties / contentAdded value: +{
+ "type": "string"
+}Input schema / properties / contentEncodingAdded value: +{
+ "type": "string"
+}Input schema / properties / filenameAdded value: +{
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "filepath",
- "deltas"
-]New value: +[]getUploadUrlmcpConvert4 fields changedInput schema / properties / contentAdded value: +{
+ "type": "string"
+}Input schema / properties / contentEncodingAdded value: +{
+ "type": "string"
+}Input schema / properties / filenameAdded value: +{
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "input",
- "outputFormat"
-]New value: +[
+ "outputFormat"
+]mcpParse4 fields changedInput schema / properties / contentAdded value: +{
+ "type": "string"
+}Input schema / properties / contentEncodingAdded value: +{
+ "type": "string"
+}Input schema / properties / filenameAdded value: +{
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "filepath",
- "outputFormat"
-]New value: +[]editDocument1 field changedInput schema / requiredPrevious value: -[
- "filepath",
- "deltas",
- "apiKey"
-]New value: +[
+ "filepath",
+ "deltas"
+]getUploadUrl1 field changedInput schema / requiredPrevious value: -[
- "filename",
- "mimeType",
- "apiKey"
-]New value: +[
+ "filename",
+ "mimeType"
+]mcpAccount1 field changedInput schema / requiredPrevious value: -[
- "apiKey",
- "action"
-]New value: +[]mcpConvert1 field changedInput schema / requiredPrevious value: -[
- "input",
- "outputFormat",
- "outputPath",
- "apiKey"
-]New value: +[
+ "input",
+ "outputFormat"
+]mcpFormats2 fields changedInput schema / properties / _Removed value: -{
- "type": "string"
-}Input schema / requiredPrevious value: -[
- "_"
-]New value: +[]mcpParse1 field changedInput schema / requiredPrevious value: -[
- "filepath",
- "outputFormat",
- "apiKey",
- "requestId"
-]New value: +[
+ "filepath",
+ "outputFormat"
+]agentCardapiSamplesapiToolscapabilitiesconvertDocumentdeviceAuthApprovedeviceAuthInspectdeviceAuthPolldeviceAuthRequestestimateformatsgetKeyUsagehealthlistApiKeysmyEntitlementsparseFileSecurepartitionGeneralpricingrequestHistoryrequestReplayrevokeApiKeyrotateApiKeyconvertDocumentparseFileSecure2 fields changedInput schema / properties / pdfBackendAdded value: +{
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "filepath",
- "outputFormat",
- "apiKey",
- "gcsRef",
- "sourceUrl",
- "editable"
-]New value: +[
+ "filepath",
+ "outputFormat",
+ "apiKey",
+ "gcsRef",
+ "sourceUrl",
+ "editable",
+ "pdfBackend"
+]submit_feedbackeditDocumentparseFileSecure2 fields changedInput schema / properties / editableAdded value: +{
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "filepath",
- "outputFormat",
- "apiKey",
- "gcsRef",
- "sourceUrl"
-]New value: +[
+ "filepath",
+ "outputFormat",
+ "apiKey",
+ "gcsRef",
+ "sourceUrl",
+ "editable"
+]Parse PDF/Word/PPT/HTML to Markdown; tables as JSON, image extraction, RAG chunking, page ranges.
Convert PDF, Word, Excel and scanned documents to Markdown, tables and RAG chunks. OCR.
Turn documents into structured data: parse, extract, classify, split, and fill PDF forms.
Extract text, pages and metadata from PDFs in bulk, with OCR for scanned files.
Add one secure layer between your agents and this server.