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

The only annotation is openWorldHint, so the description carries most of the behavioral burden. It usefully discloses credit cost and synchronous waiting, but omits timeout behavior, permission needs, and what 'the answer' contains.

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 tight sentences with the core action front-loaded and cost information clearly appended. There is no redundant or wasted wording.

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 five-parameter classification tool with no output schema, the description is too thin about what is returned and how failures or timeouts behave. It also omits the upload prerequisite workflow and alternatives that an agent would need for correct routing.

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 description clarifies that document_id refers to one uploaded document and that classes come from the account, adding some meaning beyond the schema. It says nothing about multi_class, include_unknown, or instructions, leaving clear gaps alongside the 60% schema coverage.

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 and resource: classify one uploaded document into the account's classes. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as extract or standardize.

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 implies the document must already be uploaded and that the call waits synchronously for a result. However, it gives no explicit when-to-use guidance versus extract, standardize, or list_classes, and no exclusions or failure conditions.

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?

With only openWorldHint in annotations, the description carries most of the burden and does well: it discloses that the call waits for the workbook, that results can be saved locally, that cost is upload plus 2 credits per page, and that long jobs are resumed through 'next'. It omits failure/partial-conversion behavior and what the response actually contains.

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?

Roughly four dense sentences with the core purpose first, then inputs, then cost, then resume – good front-loading and no filler. The closing "Resume with the call in 'next'" is slightly cryptic without an output schema to show what 'next' refers to.

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 seven-parameter, zero-required, no-output-schema tool, the description covers the essentials an agent needs: input alternatives, blocking-with-resume behavior, credits, and local saving. The main residual gap is that the return payload (job id, document_id, 'next') is never characterized, which matters for chaining to get_excel_conversion.

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 description usefully conveys that file_path, url, and document_id are interchangeable input routes and that save_to persists locally, which is more than the 57%-covered schema says for those fields. But schema_id and instructions go unmentioned despite being the fields that change conversion quality most, and the 'without a schema' framing sits awkwardly beside an existing schema_id 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?

"Turn a document into an .xlsx workbook" gives a specific verb and resource, and "without a schema (one sheet per table)" describes the output shape and implicitly contrasts with the schema-driven siblings like standardize/create_schema. It stops short of naming an alternative tool outright, so it lands at 4 rather than 5.

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 tells you which input forms are accepted (local file, URL, document_id) and how to resume via the 'next' call, which is genuine operational guidance. However, it never states when to pick this over standardize/create_schema, nor that at least one input identifier is required since none of the seven parameters are mandatory.

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?

The description identifies this as a save operation and mentions it is free, which is useful behavioral context beyond the openWorldHint annotation. But it does not disclose whether saving with an existing name overwrites, requires authentication, has side effects, or returns a schema ID. For a mutation tool with minimal annotations, those gaps are significant.

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 short, front-loaded with the core action, and contains no wasted sentences. The 'Free' fragment and the dense formatting tip are slightly abrupt, but both are useful and easy to scan.

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 schema-creation tool with a nested JSON Schema parameter, the description covers the core purpose and gives basic shape guidance. It remains incomplete on persistence behavior, parameter meanings, and what the call returns, especially given the lack of an output schema and only minimal annotations.

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 only 33%, so the description must carry more of the parameter burden. It gives useful guidance for the json_schema parameter by recommending type object, property descriptions, and arrays of objects for line items, but it never mentions schema_name or the optional guidelines parameter, leaving two of three parameters unclear.

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 and resource: save a JSON Schema as a DocuPipe schema. It also explains the effect, making every extraction return consistent fields. It does not explicitly distinguish this from siblings such as list_schemas or extract.

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 phrase 'so every extraction returns the same fields' implies when this tool is useful, and 'Free' adds context. However, there is no explicit guidance on when to create a schema versus using extract directly, or whether to check existing schemas with list_schemas first.

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 supply only openWorldHint, so the description carries the behavior load and does so well: it states the idempotency guarantee ('never uploads or extracts twice'), the resumption path, that the drafted schemaId is returned so later calls are stable, and a per-page credit schedule for upload and extraction. For a mutation tool with no destructive or readOnly hints, this is exactly the context an agent needs.

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 a single dense but well-ordered paragraph, front-loading what the tool does before moving to schema modes, resumption, and pricing. The credit sentences are long but each carries decision-relevant information for a cost-aware agent; nothing is clearly 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?

For a 14-parameter tool with no output schema, the description covers the operational flow, the resume path, how the schema round-trip works, and the cost profile, which is close to sufficient. The remaining gap is that the actual shape of the returned JSON beyond 'extracted data' and status 'processing' is only vaguely indicated.

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 does not: how schema_id, json_schema, and neither interact, that creating a schema from json_schema is free while drafting one costs credits on at most the first 5 pages, and the cost impact of citations and effort_level. That inter-parameter logic is genuine added value.

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 opening sentence names a specific verb and resource plus the full scope of the operation: it uploads a local file or URL (or reuses document_id), runs a DocuPipe extraction, waits, and returns structured JSON. That is enough to distinguish it from siblings like upload_document and standardize that do only one part of the pipeline.

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 conditions for each mode: pass schema_id to reuse a saved schema, json_schema to define fields inline, or neither to let DocuPipe draft one, and it says to use 'high' effort only after standard missed values. It also explains how to resume an extraction through 'next'. The only gap is that it never explicitly says when to prefer the sibling upload_document or standardize instead of this tool.

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 and openWorldHint, so the description isn't burdened with safety disclosure. It adds genuinely useful context beyond them: the returned fields (status, page count, parsed text with tables as markdown) and that calls are free, which matters for an agent deciding between paid siblings like extract.

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 short sentences, front-loaded with what is returned, followed by the optional mode and the cost note. No filler, no 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?

With no output schema, the description does the work of naming the return fields, and it covers the optional parameter's effect and cost. The main gap is behavioral edge cases such as what 'processing status' returns when parsing is incomplete, which an agent would need to handle responses.

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?

include_layout is already documented in the schema; the description restates it with the added detail of 'per-page sections with bounding boxes', which is a modest gain. document_id is undocumented in both schema and description, so half the parameters carry no semantic help.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: fetch a document's processing status, page count and parsed text, plus an optional layout mode. It's clearly the retrieval counterpart to upload_document/extract, though it never names those siblings to sharpen the distinction.

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 when-to-use or when-not-to-use guidance. With siblings like extract and convert_to_excel in the same namespace, the description leaves the agent to infer that this is the plain-text/status read path rather than the extraction or conversion path.

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 only declare openWorldHint, so the description carries the rest and does add real value: it discloses that the call blocks until the conversion finishes, that the download link is regenerated on every call (so an old link can't be reused), and that it's free. It does not say what is returned while the job is still running or on failure.

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?

One short sentence pair with the three key facts front-loaded (action, blocking wait, local save) followed by the caching and cost notes. Nothing is 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?

There is no output schema, and the description does hint at a download link in the response, but it doesn't say whether the call returns a status object, where the link appears, or what happens if the conversion failed. For a two-parameter polling tool, this is nearly complete but leaves the return shape under-specified.

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 50%; save_to is already fully documented in the schema and the description's 'optionally save the .xlsx locally' mostly restates it. The required, undocumented conversion_id is never explained — notably that it comes from convert_to_excel — so the gap is not compensated.

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 concrete verb and resource: check an Excel conversion, wait for completion, optionally save the .xlsx. It implicitly contrasts with convert_to_excel (which creates the job) but never names a sibling, so the differentiation is left to inference.

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 phrase 'wait for it to finish' implies this is called after convert_to_excel to poll/await a result, but the description never says so or explains when to use this instead of get_job or wait_for_jobs, which overlap heavily.

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 and openWorldHint=true, so safety is covered. The description does add genuinely useful non-obvious behavior: an errored job surfaces as a tool error (changing how the agent should handle the call) and the operation is free (cost-aware routing). It stops short of describing the status values or whether results appear incrementally.

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 verb and the returned payload, with the exception cases ('in error', 'for split, classify and workflow') appended compactly. Nothing is padded.

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 does the necessary work of listing return fields and job-type applicability. The main remaining gap is provenance of job_id and the set of possible status values, which an agent polling a job would benefit from.

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 job_id is a bare string, so the description carries the explanatory burden; it says only 'one job', implying job_id identifies a single job. It never says where that id comes from (returned by split, classify, run_workflow) or what an invalid/expired id does. Meaning added is real but thin.

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?

Uses a specific verb ('Fetch') and resource ('one job') and enumerates the returned fields (status, type, error message, results), plus a parenthetical restricting result availability to split, classify and workflow jobs. It does not distinguish itself from the nearby polling sibling wait_for_jobs, which keeps it from a 5.

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 definition implies the usage context (you hold a job_id from a prior async operation) but never states when to call this instead of wait_for_jobs, nor that it is a non-blocking single check. No exclusions or prerequisites are given, so the agent must infer the polling pattern.

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 the safety profile (readOnlyHint=true), so the description just needs to add context: it discloses the not-found failure mode for in-progress extractions and notes the call is free, both of which are actionable beyond the structured data. It does not describe the shape of the returned JSON or pagination, but with no output schema that gap is modest.

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 short sentences, zero padding, and the operational precondition (wait for the job) is surfaced immediately after the purpose. Every clause carries information the agent can act on.

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 simple read tool with three params and no output schema, the description plus schema cover what an agent needs to call it correctly. The only meaningful omission is a hint about the returned JSON structure and what include_field_metadata actually changes in the response.

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 67% and the description adds essentially no parameter meaning — it never explains standardization_id, save_to, or when to set include_field_metadata. The schema already documents the two optional parameters, so the baseline of 3 applies, but the description does nothing to compensate for the undocumented required id.

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?

"Fetch the extracted JSON of a finished standardization" gives a specific verb and resource, and the word "finished" scopes it to completed runs, which separates it from job-polling siblings like get_job or wait_for_jobs. It stops short of naming any sibling explicitly, so the differentiation is implied rather than stated.

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 a clear negative condition ('while the extraction is still running this answers not found') and redirects the agent to wait on the job first, which is the right behavioral routing. It does not name the specific sibling to use (get_job vs wait_for_jobs), leaving that inference to the agent.

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 establish readOnlyHint and openWorldHint, so the safety profile is covered. The description adds two things beyond that: the shape of the result (id, name, description) with no output schema available, and the cost signal "Free.", which is a genuine behavioral fact an agent cannot infer from 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?

Three short sentences, front-loaded with the resource and its returned fields, then the routing rule, then the cost. Every clause carries information; the fragment "Free." earns its place as a distinct cost signal.

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 no-parameter read tool with no output schema, the description covers what it returns, why to call it, and that it is free. Only minor items such as whether the list is paginated or how failures surface are unstated, and those are unlikely to block a correct call.

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 tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. No parameter-related gaps exist.

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?

"List the account's classification classes" gives a specific verb plus resource and even names the returned fields (id, name, description), so an agent knows exactly what this produces. It does not explicitly contrast with close-sounding siblings like list_schemas, leaving that differentiation to the resource name 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?

"classify needs class ids from here" gives an explicit prerequisite and routing rule, which is the main situation in which an agent would call this. There is no explicit when-not guidance, but a zero-parameter discovery list tool rarely has a competing alternative worth excluding.

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 and openWorldHint, so safety is covered, and the description adds genuine value on top: default ordering (newest first), the returned fields (id and name), and a cost note. The main omission is pagination behavior, which matters for an offset/limit list.

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 sentence with the resource, return fields, ordering, and purpose all front-loaded. Every clause earns its place and nothing is padded.

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 annotations covering the safety profile and no output schema needed beyond the stated id/name fields, the core is complete. However, for a paginated list tool with two fully undocumented parameters, the definition leaves the agent without enough to page correctly through results.

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 both parameters (limit and offset) carry no documented meaning anywhere. The description compensates only indirectly with 'newest first', implying an ordering that offset paginates over, but never explains the limit defaults, maximums, or how offset interacts with that ordering.

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 gives a specific verb and resource ('List the account's saved schemas') and scopes the payload to id and name, so the agent knows exactly what comes back. It distinguishes itself from create_schema implicitly via 'instead of creating a new one', though it never names the sibling tool directly.

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 usage context is provided: use this to reuse an existing schema rather than creating a new one. It also notes the call is free, which is a useful decision signal. It stops short of stating when this tool is NOT appropriate or naming alternatives by tool name.

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?

The annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful inclusion criteria and states that the operation is 'Free', but it does not describe ordering, pagination, or result shape, so it provides some behavioral context without being rich.

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 the action and scope in a single sentence, with no redundant repetition. The standalone 'Free.' fragment is slightly abrupt, but it is relevant and the overall structure is efficient.

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 no-parameter list tool with safety annotations and no output schema, the description supplies the key context: what is listed, which workflows qualify, and that the call is free. Minor operational details such as ordering or pagination are absent but not essential for invoking 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?

The tool has zero parameters, so the baseline is 4. There is no parameter meaning to add, and the description appropriately does not invent or misdescribe parameters.

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 gives a specific verb and resource ('List workflows') and defines the exact scope: workflows that run_workflow can start on one document. It also names the two workflow types and the runnable/single-document criteria, which distinguishes this from the sibling run_workflow 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?

It clearly ties the tool to the run_workflow single-document use case, implying it should be used to discover startable workflows. It does not explicitly say when not to use it or name alternatives, but the context is clear enough for an agent.

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 only supply openWorldHint=true, so the description carries most of the burden and delivers: blocking/wait semantics for Architect runs, return shape (ids of started jobs) for Classic runs, and a credit cost model (upload plus each step). Missing details are auth requirements and failure behavior, but the core behavioral profile is unusually well disclosed.

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 branching behavior is front-loaded in the first sentence, then the Classic-path routing, then cost, then resume — a sensible order with no filler. It is dense and slightly crammed (sibling names packed mid-sentence), but every clause carries 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?

With no output schema, describing returns for both workflow branches is the right call and is done. However, for a 6-parameter tool with a nested metadata object and no required fields, the unspecified dataset and metadata parameters and the undocumented source-parameter exclusivity leave real 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 coverage is only 33%, so the description must compensate; it clarifies workflow_run_job_id as the resume path and implies url/file_path as alternate source inputs, but says nothing about dataset, metadata, or that only one source parameter should be supplied. Partial compensation for a significant coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('upload a local file or URL with a workflow attached') and splits behavior by workflow type (Architect waits for outputs, Classic returns job ids), which is meaningful differentiation. It does not clearly separate itself from siblings like upload_document or standardize, leaving the agent to infer when the workflow wrapper is appropriate.

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 follow-on routing: Classic workflows require wait_for_jobs then get_standardization, and Architect runs can be resumed via workflow_run_job_id. It lacks explicit when-not-to-use guidance relative to upload_document, but the conditional paths are clearly spelled out.

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?

With only openWorldHint in the annotations, the description carries the burden and does well: it discloses that split boundaries are AI-determined (non-deterministic), that the call blocks until the new document ids are available (so no get_job/wait_for_jobs polling is needed), and it quantifies cost at 0.2 credits per page rounded up. It omits whether the original document is retained or consumed, and any permission 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?

A single front-loaded sentence where each clause carries real information (action, mechanism, blocking behavior, price). The final clause 'and wait for the new document ids' is slightly awkwardly spliced but nothing is wasted.

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?

There is no output schema, and the description correctly states the return ('the new document ids'), plus cost and blocking semantics, which covers the main things an agent needs. Remaining gaps — fate of the source document and default dataset behavior — are minor for a 3-parameter 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 67% — dataset and instructions are documented in the schema while document_id is bare — and the description only marginally compensates by clarifying that the document is an 'uploaded' one and that the AI decides boundaries (context for the instructions parameter). It adds no syntax, defaults, or format details beyond the schema.

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 verb and resource ('Split one uploaded document into sub-documents') and adds the mechanism ('AI deciding where each one starts'), which clearly separates it from siblings like extract, classify, or standardize. It never explicitly contrasts itself with those siblings, so it stops short of a 5.

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?

'one uploaded document' implies the prerequisite that the file must already exist via upload_document, but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as extract for pulling data without splitting. Usage is implied rather than stated.

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 only supply openWorldHint=true, so the description carries most of the burden and does disclose real behavior: the call blocks and waits for the result, and it documents the full credit cost model including per-page upload and extraction pricing. It omits failure/retry behavior, permission requirements, and what happens when the document is not yet fully processed – a real gap for a paid, blocking operation.

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 the sibling alternative are front-loaded, and the pricing block is dense but information-bearing rather than filler. The semicolon-chained credit sentence is somewhat hard to parse, but each clause carries distinct cost information an agent needs before calling a paid operation.

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 should say what comes back and how to retrieve results asynchronously; instead it only implies JSON via save_to. The wait/get_standardization follow-up path and the shape of the returned extraction are unspecified, which matters for a job-style tool with a documented polling sibling.

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 71%, and the description adds genuine meaning beyond it: omitting schema_id triggers drafting at 1 credit/page capped at 5 pages (free if built from json_schema), effort_level costs 2 vs 4 credits/page, and citations force standard effort at 3 credits – an interaction between two params that the schema never states. The guidelines and document_id parameters gain no added meaning, keeping this below a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run an extraction (standardization) on one uploaded, fully processed document') and constrains the input to already-uploaded, pre-processed documents. It explicitly distinguishes itself from the sibling 'extract' by scoping that tool to starting from a file.

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?

Names the alternative ('use extract instead when starting from a file') with the exact condition that selects it, which is strong guidance. However, it gives no guidance on the wait=true vs wait=false path or on when to follow up with get_standardization, leaving that choice 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 only declare openWorldHint=true, so the description carries most of the burden and delivers: it discloses that the call blocks until OCR and parsing complete, and gives concrete credit costs broken down by file type. It does not cover authentication, failure modes, or what happens when parsing fails, which keeps it below 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?

Three sentences, front-loaded with the action and the returned identifier, with the cost caveat last. Every sentence adds information an agent needs: the action, the blocking behavior, the return value, and the billing consequence.

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 five-parameter, zero-required tool with no output schema, the description covers the return value (document_id) and cost profile well. The gap is that zero required parameters means an agent could call it with neither url nor file_path, and the description never states that exactly one source is needed.

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: which file types are supported and which are billed versus free. The 'local file or URL' phrasing also reinforces the file_path/url mutual exclusivity that the schema only implies via 'instead of file_path'.

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 verb (upload) and resource (local file or URL), states what happens next (OCR and parsing), and names the artifact produced (document_id). The phrase 'used by every other tool' also positions it against siblings such as extract and get_document as the entry point of the pipeline.

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 makes clear this is the first step ('Returns the document_id used by every other tool'), which tells an agent when to reach for it before extract or get_document. It does not name explicit alternatives or state when not to use it, nor when to set wait to false.

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 and openWorldHint, so the safety profile is covered, and the description adds real behavior: early return on all-done or first failure, the need to re-invoke for pending jobs, the meaning of an 'unknown' id, and that the call is free. It does not mention the upper bound on waiting time, which is a minor omission given the schema declares it.

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?

Four short sentences, front-loaded with the core behavior and ending with the failure/diagnosis note and cost. No filler and every clause carries usable 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?

With only two parameters, no output schema, and read-only annotations, the description covers what an agent needs: waiting semantics, early-exit conditions, re-polling, and unknown-id diagnosis. The only gap is the absence of any guidance on the wait-duration parameter.

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 parameter meaning. It clarifies job_ids as the listed jobs of any type and explains the consequence of an unrecognized id, but max_wait_seconds is never mentioned, leaving the wait-control parameter documented only by its schema bounds.

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 uses a specific verb and resource ('Wait until the listed jobs finish ... report each one's status') and explicitly scopes it to 'any job type', which distinguishes it from the single-job sibling get_job. It is clear what the tool does, though it does not state outright that polling a single job should use get_job instead.

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 concrete call-again guidance ('Returns early when all are done or one fails; call again if some are still processing') and routes the agent to get_job for ids that stay 'unknown'. What is missing is an explicit statement of when to prefer get_job or how often to re-poll.

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