Deterministic DOCX/PPTX/XLSX/PDF parser: track changes, comments, headers, footers, merged cells.
Scored across 10 tools
Most tools have distinct purposes: parsing, editing, conversion, estimation, formats, auth, account, upload, and feedback. editDocument and mcpParse both parse, but editDocument explicitly applies deltas, making them distinguishable. Auth tools (mcpAuth, mcpAuthPoll) are clearly separate.
Naming is inconsistent. Most tools use an 'mcp' prefix (mcpParse, mcpConvert, etc.), but editDocument and getUploadUrl do not, and submit_feedback uses snake_case while others use camelCase. This mixed convention undermines predictability.
10 tools is well-scoped for a document parsing service. It covers core operations (parse, edit, convert), auxiliary needs (estimate, formats, upload), and account/auth management. Each tool has a clear role without redundancy.
The surface covers the primary lifecycle: parse, edit, convert, estimate, and format discovery, plus auth and account management. Missing history deletion is a deliberate design choice, and request replay is reserved for future use, so no critical gaps exist.
Parse a document, apply JSON edit deltas, and return the modified blocks as JSON (same format as POST /api/v1/parse with outputFormat=blocks).
filepath: uploaded file path (multipart upload). deltas: JSON array of edit operations — see edit_apply.ail for format. Empty array or "" → round-trip (parse + return unchanged blocks). apiKey: dp_ API key.
Response: modified blocks JSON. Use the AILANG SDK or CLI to generate a file from the returned blocks (e.g. ailang run ... --convert output.docx).
Only deterministic office formats are supported (docx, pptx, xlsx, odt, odp, ods). AI-required formats (pdf, image, audio, video) are rejected.
| Name | Required | Description | Default |
|---|---|---|---|
| apiKey | Yes | ||
| deltas | Yes | ||
| filepath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains core behavior (apply deltas, return blocks), the round-trip behavior for empty deltas, the response format, and supported/rejected file types. It could add details about error handling or invalid deltas, but is otherwise transparent.
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 description is structured with clear separation for main behavior, parameter details, response, and format constraints. Every sentence contributes useful information, with no filler or redundancy.
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?
Despite having no output schema and no annotations, the description covers the input parameters, output format, how to use the result (AILANG SDK/CLI), and format restrictions. It is sufficiently complete for an agent to select and invoke the tool 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 description coverage is 0%, so the description must compensate—and it does. It explains filepath (uploaded file path), deltas (JSON array, format reference, empty array behavior), and apiKey (dp_ API key). This is meaningful semantic detail beyond the plain schema strings.
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 starts with a specific verb+resource: 'Parse a document, apply JSON edit deltas, and return the modified blocks as JSON.' It clearly defines what the tool does and differentiates it from sibling parse-only tools like mcpParse by emphasizing the delta application and round-trip behavior.
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 description provides clear context on when to use the tool: for deterministic office formats (docx, pptx, xlsx, etc.) and explicitly states that AI-required formats (pdf, image, audio, video) are rejected. It also advises using the AILANG SDK/CLI for conversion, but does not explicitly name alternative MCP tools for parsing-only tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request a pre-authenticated GCS upload URL for direct file upload. Business tier only. The returned URL allows the client to PUT file content directly to GCS, bypassing the 32MB Cloud Run request limit. After upload, pass the gcs_ref to POST /api/v1/parse.
| Name | Required | Description | Default |
|---|---|---|---|
| apiKey | Yes | ||
| filename | Yes | ||
| mimeType | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the returned URL is pre-authenticated and allows the client to PUT content directly to GCS, bypassing the size limit. It also notes the Business tier restriction and the follow-up step. However, it omits important details such as URL expiration, whether the URL is single-use, error conditions, or authentication specifics, leaving some behavior undocumented.
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 description is three sentences, front-loaded with the primary purpose, followed by constraints and the follow-up workflow. Every sentence earns its place with no redundancy or fluff. The structure is clear and highly scannable.
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?
The tool has 3 required parameters, no annotations, and no output schema. The description explains the high-level workflow but omits crucial details such as parameter meanings, response format (only mentions 'returned URL' and 'gcs_ref' without structure), possible errors, and the role of apiKey. This makes the description incomplete for a tool with no other structured documentation.
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?
The schema defines three parameters (apiKey, filename, mimeType) with no descriptions, and schema description coverage is 0%. The description adds absolutely no information about these parameters, not even mentioning them. This is a critical gap: the agent is left to infer parameter meaning from names alone, which is insufficient for a tool with this level of ambiguity.
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 clearly states the tool's function: 'Request a pre-authenticated GCS upload URL for direct file upload.' It identifies the action (request), resource (GCS upload URL), and scope (direct file upload). This distinguishes it from sibling tools like parseFileSecure by focusing on the upload step, making the purpose unambiguous.
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 description gives clear usage context: use this for direct file uploads to GCS, specifically to bypass the 32MB Cloud Run request limit. It also outlines a workflow by mentioning the need to pass gcs_ref to POST /api/v1/parse after upload. However, it doesn't explicitly name alternatives or state when not to use the tool, so it misses a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
View account info, pricing, entitlements, or list keys. Actions: "status" (default) → tier, quota, usage from /me/entitlements "pricing" → public pricing tiers (no auth required) "keys" → list user's API keys with per-key usage "usage" → alias for "keys" (per-key usage is shown there) "history" → whether request history (parsed output kept for replay) is on for this account "history_on" / "history_off" → change it for the account and all its keys Deleting history is deliberately not an MCP action: it stays on POST /api/v1/requests/delete and the dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| apiKey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses the no-auth nature of pricing, the alias between usage and keys, the account-wide effect of history_on/off, and the deliberate exclusion of deletion. It does not discuss side effects of toggling history or error behavior, but the core behaviors are transparent.
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 description is front-loaded with a clear summary, followed by a compact action list where every line adds distinct value. The deletion note is relevant and prevents misuse without unnecessary verbosity.
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?
The description covers most actions and even a non-action, but it omits the meaning/source of apiKey, gives only partial return-value information for some actions, and does not resolve the required-apiKey vs no-auth tension. Since there is no output schema, more return detail would be expected for full completeness.
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?
The action parameter is well documented with enumerated values and semantics, which compensates for the schema's bare string type. However, apiKey is not explained, and there are conflicts: the schema requires apiKey while the description says pricing needs no auth, and action is required while the description calls status the default. This undermines full parameter clarity.
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 clearly states the resource (account) and the operations: view account info, pricing, entitlements, or list keys. The action list removes ambiguity, and the explicit note that history deletion is not an MCP action further distinguishes this tool's scope from related endpoints.
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 guidance per action, notes that pricing requires no auth, and explicitly says history deletion is not an MCP action, directing the user to POST /api/v1/requests/delete and the dashboard. This is a clear when-to-use and when-not-to-use statement.
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?
With no annotations, the description carries the burden and delivers useful context: it discloses return values, the interactive user step, and the caveat that MCP wrappers lack HTTP headers so provenance is empty. It does not discuss permissions or errors, but it goes beyond the schema.
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 description is concise, logically structured, and packed with actionable information across four sentences. No redundancy or 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?
It explains the authorization flow, return values, and next step, which is sufficient for the tool's purpose. However, the unexplained 'label' parameter prevents full completeness.
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?
The sole required parameter 'label' is completely undocumented in the schema (0% coverage) and never mentioned in the description. The agent has no guidance on what value to provide for this mandatory field.
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 clearly states it starts device authorization to get an API key, and specifies the return values (device_code, user_code, verification URL). It distinguishes itself from mcpAuthPoll by framing this as the initial step of the flow.
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 provides explicit workflow instructions: display the verification URL to the user, wait for approval, then call mcpAuthPoll. It does not name alternatives or exclusions, but the sequential context makes when to use this tool clear.
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?
With no annotations, the description carries the full burden of explaining behavior. It discloses the three possible return states ('pending', 'approved', 'expired') and associated outcomes (api_key and tier on approval). It also gives operational guidance (polling interval and recovery action). It does not mention error handling for invalid device codes, but the key behavioral traits are covered.
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 description is extremely concise: two sentences total. It front-loads the primary action ('Poll for device authorization completion') and then lists the return values and resulting actions. Every sentence earns its place with no fluff or repetition.
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?
Given the tool's simplicity (one parameter, no output schema), the description covers the main behavioral aspects: return statuses, polling interval, and next steps. It does not detail error cases (e.g., invalid deviceCode) or exact structure of api_key/tier, but for a poll tool this is reasonably complete. The lack of an output schema makes the return value explanation essential, and it is provided.
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?
The input schema has one parameter (deviceCode) with 0% schema description coverage, so the description must compensate. It does not explicitly describe what deviceCode is, where it comes from, or format requirements. The context implies it comes from mcpAuth, but this is not stated directly. The description adds minimal value beyond the schema parameter 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?
The description clearly states the tool's purpose with a specific verb ('Poll') and resource ('device authorization completion'). It explains the three possible outcomes, which makes the tool's function unambiguous. However, it does not explicitly differentiate from the sibling tool 'deviceAuthPoll', which may have similar functionality.
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 description provides clear usage context: poll every 5 seconds while pending, and start over with mcpAuth on expiry. It implies the tool is part of a device authorization flow. It does not explicitly state when not to use it or compare it to the similar sibling 'deviceAuthPoll', but the guidance given is actionable and useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a document to another format. Targets: html, md, qmd, docx, pptx,
xlsx, odt, odp, ods. input is a file path, a sample_id, an https:// URL,
or a gs:// ref (Business tier).
The converted file comes back as base64 in the JSON response rather than
written to disk, so decode content to get the bytes. outputPath is
accepted but ignored; it stays in the signature because removing it would
change the auto-generated MCP tool schema for existing clients.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | ||
| apiKey | Yes | ||
| outputPath | Yes | ||
| outputFormat | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses key behavioral traits: the converted file is returned as base64 in the JSON response, not written to disk, and 'outputPath' is accepted but ignored. This is valuable transparency beyond the schema.
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 description is concise and well-structured, with two paragraphs that front-load the purpose and targets, then detail the behavior. Every sentence adds value, covering the output format and the 'outputPath' gotcha without extraneous information.
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?
The description explains the return format (base64 in JSON) and the ignored output parameter, which is key for a conversion tool without an output schema. However, it does not specify supported input formats, error handling, or limits, leaving notable gaps for a tool with no annotations and no output schema.
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 compensates well by explaining 'input' (file path, sample_id, URL, gs://), 'outputPath' (ignored), and implicitly 'outputFormat' via the list of target formats. However, 'apiKey' is not explained, though it is self-explanatory.
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 clearly states the tool converts a document to another format and lists the target formats. However, it does not differentiate from the sibling tool 'convertDocument', which likely serves a similar purpose, so it lacks explicit sibling differentiation.
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 description provides context on when to use the tool by listing input types (file path, sample_id, URL, gs://) and notes the Business tier requirement for gs:// refs. It implies usage but does not explicitly state when to choose this over alternatives like 'convertDocument'.
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?
No annotations are provided, so the description carries the full burden. It reveals that no auth is required, which is a useful behavioral detail, and specifies input constraints. However, it does not disclose whether the operation is read-only, what happens on invalid input, error behavior, or response structure. These gaps are expected for a simple estimate tool, but it does not fully compensate for missing annotations.
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 description is two concise sentences, with the purpose front-loaded and no extraneous content. Every word adds value, making it easy to parse and understand quickly.
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?
Given the tool has only two simple parameters and no output schema, the description provides a reasonable baseline. However, it fails to clarify the relationship between 'file path' and 'sample_id' (which is not in the schema) and does not describe the output format. The absence of annotations and output schema increases the need for more detail, which is only partially met.
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. It mentions 'file path or sample_id', but the schema only lists 'filepath' and 'outputFormat' as required properties, creating a discrepancy about sample_id. The description does not explain the 'outputFormat' parameter or its possible values, leaving the agent with ambiguous parameter semantics.
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 clearly states the tool's function: 'Estimate cost and latency for parsing a document.' This gives a specific verb and resource, and mentions accepted inputs (file path or sample_id). However, it does not explicitly distinguish this tool from the sibling 'estimate', leaving some ambiguity about when to choose which.
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 description implies usage when cost/latency estimation for parsing is needed, but it provides no explicit guidance on when to use this tool versus alternatives like 'estimate' or 'mcpParse'. It mentions acceptable input types (file path or sample_id) but lacks any exclusions, prerequisites, or comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Supported formats, samples, and service capabilities. No auth required. Delegates to package implementation. Single source of truth lives in pkg/sunholo/ailang_parse/services/mcp/tools — since ailang_parse 0.39.x the response carries a runtime capability block (state, not intent), which is why this is no longer pure: it reads env and probes the runtime (Process).
| Name | Required | Description | Default |
|---|---|---|---|
| _ | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the tool 'reads env and probes the runtime (Process)' and that the response carries a 'runtime capability block (state, not intent),' which is meaningful transparency beyond a simple 'returns formats' statement. It could still mention return structure or potential failure modes, but the behavioral disclosure is well above average.
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 capability is front-loaded, but the description includes internal implementation details like the package path and a version-history explanation ('since ailang_parse 0.39.x...') that are not essential for correct invocation. It is not bloated, but it carries more developer-context prose than necessary.
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?
The tool has no annotations, no output schema, and an undocumented required parameter, so the description must fill a large gap. It provides useful runtime-behavior context, but it never explains the required '_' input or the shape of the returned formats/samples/capabilities block. An agent cannot confidently call this tool correctly from the given information.
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 the single required parameter '_' is not explained anywhere in the description. An agent has no idea what value to pass or what role the parameter plays. The behavior notes about env/runtime probing do not clarify this parameter.
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 'Supported formats, samples, and service capabilities,' which clearly indicates the tool exposes informational content rather than performing a transformation like mcpConvert or mcpParse. It is not a tautology and gives a reasonable sense of the resource, though it lacks an explicit verb like 'list' or 'return' and does not directly distinguish itself from siblings.
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?
There is no guidance on when to use this tool versus mcpParse, mcpConvert, mcpEstimate, or mcpAccount. 'No auth required' is an access note, not a usage condition. No alternatives, exclusions, or invocation context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse a document. Accepts a file path or sample_id (e.g. "sample_docx_formatting"). The hosted server requires a valid dp_ API key — get one via mcpAuth. Output formats: blocks (default), markdown, html, a2ui. requestId is reserved for future replay support.
| Name | Required | Description | Default |
|---|---|---|---|
| apiKey | Yes | ||
| filepath | Yes | ||
| requestId | Yes | ||
| outputFormat | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals auth requirements, output format options with a default, and the non-functional requestId. This is strong transparency for a parse operation, though it doesn't discuss side effects or error 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?
Three sentences, front-loaded with purpose, and every sentence adds information. No redundancy or 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?
Covers key aspects like inputs, auth, output formats, and requestId. However, requestId is required but its expected value is vague ('reserved for future replay'), no return structure is described, and there is no differentiation from sibling tools. These gaps prevent a higher score.
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%, so the description must compensate. It explains filepath (or sample_id), outputFormat options, apiKey requirement, and requestId purpose. This adds substantial meaning beyond the bare schema, though exact format or allowed values are not fully specified.
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?
Clearly states 'Parse a document' and identifies key inputs (file path or sample_id) and output formats. However, it does not explicitly distinguish this tool from sibling parse tools like parseFileSecure or partitionGeneral, so it misses the top score.
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 clear context: requires a dp_ API key, lists output formats, and notes requestId is reserved for future replay. Does not explicitly say when to use this instead of alternatives, but the prerequisite and parameter details provide good usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
No annotations are provided, so the description carries the full burden. It discloses key behaviors: queued (not immediate), anonymous, body/snippet limits, contact field opacity, and the effect of auto_dispatch (immediate action vs human triage, separate sprint). This is comprehensive and beyond what any structured fields would provide.
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?
Despite covering many details (routing, limits, categories, auto_dispatch), the description remains dense and efficient. It front-loads the core purpose and routing, then appends essential constraints. Every sentence adds value, with no fluff.
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 8 parameters, no output schema, and no annotations, the description provides comprehensive context: default routing, package routing, limits, category enum, contact field behavior, and auto_dispatch implications. It fully prepares an agent to invoke the tool correctly, even without schema descriptions.
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 covers 100% of parameters, but the description adds meaningful context beyond schema descriptions: the 'package' param's routing to an agent-watching inbox, and auto_dispatch's 'files for human triage' and 'separate sprint' nuance. While the schema already explains most parameters, the description enriches the behavioral understanding of routing and dispatch.
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 clearly states the tool's purpose: 'Anonymous bug report / feature request / docs gap, queued for human review.' This specifies the verb (submit), the resource (feedback), and the scope (bug/feature/docs), distinguishing it from sibling tools which are mostly API/auth utilities. The purpose is immediately evident and unambiguous.
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 explicit routing guidance: default to public-feedback inbox, or pass package to route to a package-specific inbox. It explains when to set auto_dispatch=true (to authorize package agent) versus default (human triage), and mentions categories. This gives clear context for when and how to use the tool versus alternatives.
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.
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"
+]agentCardapiSamplesapiToolscapabilitiesdeviceAuthApprovedeviceAuthInspectdeviceAuthPolldeviceAuthRequestestimateformatsgetKeyUsagegetUploadUrlhealthlistApiKeysmcpAccountmcpAuthmcpAuthPollmcpConvertmcpEstimatemcpFormatsmcpParsemyEntitlementsparseFileSecurepartitionGeneralpricingrequestHistoryrequestReplayrevokeApiKeyrotateApiKeyParse PDF/Word/PPT/HTML to Markdown; tables as JSON, image extraction, RAG chunking, page ranges.
Turn documents into structured data: parse, extract, classify, split, and fill PDF forms.
High-fidelity PDF to structured Markdown conversion and document field extraction.
Extract tables, text and formulas from PDFs, including scanned pages and broken text layers.
Add one secure layer between your agents and this server.