Deterministic DOCX/PPTX/XLSX/PDF parser: track changes, comments, headers, footers, merged cells.
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)
| 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 full burden. It discloses that 'pricing' requires no auth, that 'keys' returns per-key usage, and that 'usage' is an alias. This is useful behavioral context beyond the schema, though it omits error handling or apiKey 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?
The description is front-loaded with a one-line summary and uses a clear bulleted list for actions. No redundant information or padding.
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 2 required params, no output schema, and no annotations. The description thoroughly explains each action's result and auth requirements, but misses context on apiKey acquisition and when to prefer this tool over specialized 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?
Schema coverage is 0%, and the description adds meaning for the 'action' parameter by enumerating valid values and their meanings. However, the required 'apiKey' parameter is entirely unexplained, leaving a significant 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?
The description opens with 'View account info, pricing, entitlements, or list keys' followed by a detailed action list, making the tool's purpose explicit and distinguishing it from specialized siblings like listApiKeys and pricing.
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 lists actions but does not explain when to choose this aggregate tool over dedicated siblings (e.g., listApiKeys, getKeyUsage, myEntitlements). No exclusions or alternatives are mentioned, so usage guidance is implied rather than explicit.
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. Dates show when Glama detected each change.
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"
+]agentCardapiSamplesapiToolscapabilitiesdeviceAuthApprovedeviceAuthInspectdeviceAuthPolldeviceAuthRequestestimateformatsgetKeyUsagegetUploadUrlhealthlistApiKeysmcpAccountmcpAuthmcpAuthPollmcpConvertmcpEstimatemcpFormatsmcpParsemyEntitlementsparseFileSecurepartitionGeneralpricingrequestHistoryrequestReplayrevokeApiKeyrotateApiKeyClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Parse 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.
Most tools have clear, distinct purposes: parse, convert, estimate, formats, auth, auth-poll, account, upload, and feedback. The main ambiguity is that editDocument with an empty delta array behaves like a parse, overlapping with mcpParse.
Seven tools share a useful mcp prefix with PascalCase, but editDocument and getUploadUrl are camelCase and submit_feedback is snake_case. The casing and verb-style inconsistencies make the tool set feel less coherent than its overall design suggests.
Ten tools is a well-scoped size for this domain: authentication, account, upload, formatting, estimation, parsing, editing, conversion, and feedback are each represented. No tool feels redundant or like filler.
The surface covers the key parse workflow: get an API key, upload, estimate, parse, edit, convert, and check supported formats. Minor gaps exist, such as no explicit API-key revoke action and some output/workflow steps being delegated to the SDK/CLI.