AILANG Parse

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.

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.

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.

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.

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.

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

Annotations already declare readOnly/non-destructive/open-world, and the description goes further: the result carries a download_url valid for one hour, the file also comes back base64 (utf8 for text formats), and outputPath must be left empty because the server cannot write to the caller's filesystem. It omits authentication (the apiKey parameter is never mentioned) and any error/size-limit behavior, so it is strong but not complete.

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 purpose and format list are front-loaded, and the body is organized as labelled input options plus a decision list for upload paths, which is appropriate for a 9-parameter tool. It is somewhat repetitive (the 'give it ONE way' modes are restated in the which-way list) and dense, but nearly every line carries a routing constraint.

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 documents the return payload (download_url, base64/utf8 content), the one-hour link lifetime, and the outputPath caveat, which is what an agent needs to finish the task. Given 9 parameters and 0% schema coverage, the remaining gap is authentication (apiKey) and failure modes such as unsupported formats or oversized inputs.

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 carries the burden, and it does so well: it explains the mutually exclusive input modes (fileRef / file / content+filename / input) that the schema expresses only as loose optional properties, and it names the values for outputFormat and contentEncoding. The apiKey parameter is never explained, and no enum is given for outputFormat beyond the prose list.

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 first sentence states a specific verb+resource (create/convert a document) plus the exact output formats supported (docx, pptx, xlsx, odt, odp, ods, html, md, qmd). It also disambiguates from siblings by naming createUpload and uploadDocument as the upload paths, and mcpFormats as the sample-id source, so an agent can route without opening other schemas.

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?

Explicit when-to-use routing is given for every input mode (fileRef for uploaded files, file for ChatGPT attachments, content+filename for inline documents, input for public https URLs or mcpFormats sample ids) and for the two upload mechanisms (createUpload vs uploadDocument, with the trigger conditions for each). It even states a negative rule: never parse the file yourself and present that as this tool's result.

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

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.

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.

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

Goes well beyond the annotations: it discloses the 30-minute fileRef lifetime and deletion, that AI-mode PDF parsing costs ~5s per page and counts as an AI request, that pdfBackend must be repeated across cursor calls, and that all parts must be read before answering about the whole document. These are exactly the non-obvious behavioral costs and constraints an agent needs, and they are consistent with readOnlyHint/openWorldHint/idempotentHint=false.

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, then organized into labeled sections (input routes, outputFormat, pagination, pdfBackend, how to send a file) with indented bullets that make scanning easy. It is longer than most descriptions, but nearly every line conveys a distinct operational rule; the repetition of fileRef/filepath in the cursor paragraph is minor.

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 12-parameter, branching tool with no output schema, the description covers input selection, output format semantics, pagination protocol, cost/speed implications, and cross-tool routing. The only real gaps are the auxiliary parameters (apiKey, requestId, contentEncoding) and error-shape detail, which are secondary given the tool's complexity is otherwise fully addressed.

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 carries the load well, explaining fileRef format, filepath accepted values, content+filename extension-driven parsing, outputFormat options, cursor usage, maxChars default and range, and pdfBackend values. However apiKey, requestId, and contentEncoding are never mentioned, so three of twelve parameters remain undocumented anywhere.

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?

Names a specific verb and resource ('parse a document') and enumerates the concrete outputs (blocks, markdown, html, a2ui, summary), which lets an agent distinguish it from mcpConvert and mcpFormats named in the sibling list. An agent knows exactly what it gets back 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?

Explicitly says 'Give the document ONE way' and then routes each situation: fileRef for already-uploaded files, file for ChatGPT attachments, filepath for public URLs or sample ids, content+filename for short text, plus a decision tree pointing to createUpload or uploadDocument when the file isn't reachable otherwise. It also advises calling with summary first for large documents and warns never to substitute your own parsing, leaving almost nothing to inference.

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

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.

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.

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.