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

Annotations already declare destructiveHint and idempotentHint, but the description adds real substance beyond them: deleted IDs cannot be reused for later retrieval or exports, local input/exported files are untouched, and repeat deletion is a no-op whose returned boolean may still change. That last note directly explains an idempotency nuance 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-loads the action and the ID disambiguation, then layers preconditions, side effects, and idempotency. Five sentences, each carrying distinct information; nothing is redundant with 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?

An output schema exists so return values need no explanation, and the description covers everything else an agent needs: correct ID type, deletion preconditions, irreversibility for downstream retrieval, scope of deletion, and repeat-call behavior.

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 sharply clarifies what document_ids must be (not task IDs, export job IDs, or paths), adding meaning beyond the schema's terse 'Suparse document IDs to delete.' However, api_url is undocumented in both schema and description, so with 50% coverage the description only partly compensates for the 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 ('Delete documents from Suparse') and immediately disambiguates the ID domain from siblings: 'using document IDs, not task IDs, export job IDs, or local paths.' An agent can distinguish this from get_task_results, download_results, or export tools without opening 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?

Gives an explicit precondition gate: 'Use only when deletion or cleanup is requested, after confirming any required results are safely saved.' Clear on when to invoke, though it does not name a specific sibling alternative (e.g. 'to retrieve instead, use get_task_results') by 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?

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds real behavioral context beyond them: byte fidelity including ZIP, no parsing/unpacking, size and SHA-256 verification before atomic publication, overwrite defaulting to false, and the irreversibility of an expired artifact. This is unusually complete disclosure for a write-to-disk tool.

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 action and its boundaries are front-loaded in the first two sentences, followed by verification behavior and the two caveats (overwrite, expired artifact). Dense but every sentence carries operational information with no 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?

An output schema exists so return values need not be detailed, yet the description still notes it returns output_path. Combined with preconditions, failure modes (expired artifact), and byte-preservation behavior, nothing needed to invoke this tool correctly is missing.

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 75% and the schema already documents overwrite (with default) and output_path (with path semantics and ZIP caveat). The description restates overwrite's default and intent but adds no new syntax or format detail, so it largely duplicates structured data. Baseline 3 is appropriate.

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: 'Save the artifact of an existing completed export_job_id to local disk.' It also draws explicit boundaries against siblings by declaring it does not submit another export, wait for completion, or parse/unpack the artifact, which separates it from download_results, get_export_job, and wait_for_export_job.

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 routing: 'Use get_export_job or wait_for_export_job first if needed,' and states the precondition that the job must already be completed. It also gives the condition for overwrite ('enable only when replacing a local file is intended') and warns that retrying cannot recover an expired artifact.

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 destructiveHint=true and openWorldHint=true, and the description sharpens that: it warns existing local output files are overwritten, explains CSV/XLSX may return a ZIP whose extension is corrected to .zip, notes Google Sheets needs an immediate API response and saves only metadata, and clarifies the destructive scope is local (does not delete remote documents). This adds real context beyond the annotation flags.

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?

Dense but front-loaded around the core export action, with overwrite and ZIP caveats in the middle and the alternative routing at the end. Nearly every sentence carries actionable detail, though the format/metadata sentences are somewhat packed and could be tightened.

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?

An output schema exists, so return-value explanation is not required, yet the description still summarizes output_path/artifact_format. For a 9-parameter destructive export tool it covers overwrite risk, ZIP behavior, Google Sheets constraints, and the sibling alternative, leaving nothing critical implied.

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 89%, so the schema already documents most parameters (baseline 3). The description still adds meaning on top: unpack extracting into a fresh folder with output_paths, JSON saved as parsed task groups, and CSV/XLSX ZIP behavior. It slightly exceeds the schema-only baseline but does not cover every parameter (e.g., idempotency_key, wait_timeout_ms).

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 ('Export existing Suparse document IDs as JSON, CSV, XLSX, or Google Sheets to local disk') and the scope of the operation. It also distinguishes itself from the sibling download_export_job by naming that tool for the known-export_job_id case, so an agent can route 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 concrete when-to guidance (choose a new path unless replacement is intended; set unpack:true to also extract separate files) and one explicit alternative ('For a known export_job_id use download_export_job'). It also excludes delete_documents by stating it does not delete remote documents, but it does not explicitly contrast with the extraction/result siblings like get_task_results or fetch_json_results.

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?

Adds substantial context beyond the annotations: partial tasks retain status, auto_approve=false can cause the combined tool to wait and time out during human review, return_json consumes context and reports partial/empty exports as incomplete, and cleanup is best-effort, return_json-only, and gated on a completed task with full export coverage. This explains the destructiveHint behavior (remote document deletion) rather than contradicting 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?

Front-loads the default behavior before alternatives, and every sentence carries operational content. Sentences are long and dense for a 10-parameter tool, but there is little 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 the key ambiguities of a combined extract-and-wait tool (partial tasks, approval timeouts, export vs. defer, cleanup constraints), and an output schema exists so return-value detail is not needed. Minor gaps remain around resumed exports and how defer results feed later export steps.

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 90%, so the schema already documents most parameters; the description nonetheless adds meaning about result_mode defaults, the defer/return_json behavioral difference, wait_timeout_ms applying per-export in JSON mode, and cleanup's preconditions. It adds value but largely restates schema-documented 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?

States a specific verb+resource+scope: 'Process one local file through Suparse,' with the default flow spelled out (upload, wait for terminal processing, return task_id/document_ids). This cleanly separates it from extract_folder and the start_file_extraction/wait_for_task_extraction 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?

Explicitly routes to alternatives: use start_file_extraction for an immediate task ID, and download_results for large results or other export formats. It also warns that result_mode defer 'does not mean background processing.' It stops short of a full when-to-prefer-this-over-the-start-only-pipeline statement, but the context is clear.

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 give safety hints (destructive, open-world, non-idempotent), and the description adds substantive context beyond them: concurrency cap of 10, the default defer behavior, the timeout risk while human review is pending, cleanup being best-effort and constrained, and that partial tasks/empty exports are reported as incomplete.

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?

Main purpose and scope are front-loaded in the first sentence, and each sentence carries distinct operational information. It is dense and clause-heavy for a 10-parameter tool, but little of it 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?

For a complex 10-parameter tool with an output schema and mutating side effects, the description covers modes, timing, approval, cleanup constraints, and separation of concerns. An agent has enough to invoke it correctly; return values are handled by the 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?

Schema coverage is already 90%, so the schema carries most burden (baseline 3). The description nonetheless adds cross-parameter meaning the schema doesn't fully convey, such as result_mode's defer-vs-background distinction and the fact that cleanup is only valid with return_json and a fully covering export.

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 (process), resource (sorted immediate supported files in a local folder), and scope (nonrecursive, directories skipped). It explicitly names the sibling start_folder_extraction and the condition that routes to it, so the agent can distinguish it without opening 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?

Provides explicit when-to-use guidance: defer vs return_json semantics, use start_folder_extraction for task IDs before processing completes, and download_results for large results. It also states exactly when cleanup is permitted and when auto_approve=false applies, covering alternatives and 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?

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuinely non-derivable behavior: it does not create an export job, does not write a local file, and does not block waiting for extraction to complete. It also names the returned fields, though with an output schema present that is somewhat redundant.

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, each load-bearing: what it returns, where the ID comes from, and which siblings to use instead. The core capability and its non-blocking nature are front-loaded with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-resource read with an output schema, the description supplies everything an agent needs: ID sourcing, sibling alternatives, async behavior, and no side effects. Annotations cover the safety dimension and the output schema covers the return shape, so nothing material is missing.

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 50%, so the description must compensate, and it does for the required parameter by clarifying the provenance of document_id (extraction results / get_task_results documents[].id) and warning against passing a task_id. It does not cover the undocumented api_url parameter, leaving one gap.

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

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

States a specific verb and resource ('Read structured JSON for one processed Suparse document_id') and immediately scopes it ('directly, without submitting an export job or saving a local file'). This distinguishes it from fetch_json_results and download_results without the agent needing to open sibling 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?

Gives explicit when-to-use routing ('Use fetch_json_results for a multi-document JSON export or download_results to save an export') and a prerequisite for the ID ('Get document IDs from extraction results or get_task_results (documents[].id); do not substitute a task_id'). It also states the exclusion 'Does not wait for extraction to finish,' covering the alternative of waiting tools.

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 cover readOnly=false, destructive=false, openWorld=true, so the description carries real weight and does: it discloses the timeout fallback (retain export_job_id or replay with the retained idempotency_key), confirms no document deletion, and points cleanup at delete_documents. This is behavioral context well beyond the annotations and consistent with them.

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 what the tool does before the routing guidance, and every sentence carries a distinct rule (alternatives, format limits, timeout recovery, deletion boundary). It is dense and runs long, 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 an output schema present, the description needn't explain return values, and it doesn't. Between the annotations, the rich schema, and the description's coverage of alternatives, format limits, timeout recovery, and delete semantics, an agent has everything needed to invoke this 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 already 80% and the schema documents export_type defaults and wait_timeout_ms semantics thoroughly. The description adds meaning the schema does not, specifically the retention/replay contract for export_job_id and idempotency_key, which is the key parameter concern for this tool.

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 (export) and resource (existing Suparse document IDs) and states the output shape (grouped by task in results with named fields). It also explicitly contrasts itself with fetch_document_result and download_results, so an agent can distinguish this tool from its closest siblings without opening 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 fetch_document_result for a direct single-document read, use download_results for large results, local files, CSV, XLSX, or Google Sheets. It also states a negative boundary ('only exports JSON and does not unpack ZIP artifacts'), which prevents misselection for those cases.

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description adds concrete behavior beyond them: it does not wait or download, it enumerates return content, and it warns that status/format strings may contain client-unknown values. The forward-compatibility caveat is a genuine behavioral disclosure 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?

Every sentence carries routing or disambiguation value, and the primary identity of the tool is front-loaded in the first clause. Despite being information-dense, 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?

An output schema exists so return values need no elaboration, yet the description still summarizes them briefly for routing purposes. Combined with clear preconditions, alternates, and caveats, an agent has everything needed to call this 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 50% – export_job_id is documented but api_url is not. The description compensates by characterizing the ID's origin and explicitly excluding task_id/document_id, which is more valuable than a generic format hint. It does not explain api_url, keeping it just short of 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?

The description states a specific verb and resource ('Check one existing export_job_id') and immediately disambiguates the identifier type ('this is not an extraction task_id or document_id'), which is the key confusion risk given the sibling extraction tools. An agent can distinguish it from get_task_results and the export siblings without opening 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: use wait_for_export_job if still running, then download_export_job once complete, and it warns to inspect exclusions/errors before assuming success. It also anchors the input to 'an export response or error recovery', telling the agent where the ID comes from.

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 carry readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds genuine behavioral context beyond that: it is non-blocking, it returns result.status plus progress/template IDs/saved document IDs or failure details, and it must not be substituted for starting a run. It does not describe rate limits or retry cadence, but the 'call again later' phrasing covers the polling model.

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 action and its non-blocking constraint, then routed answers about the result fields. Four sentences that each carry information, though the template_id/saved_document_id sentence is somewhat dense and could be tightened since an output schema exists.

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 an output schema exists, the description need not enumerate return values, yet it usefully summarizes status, progress, IDs, and failure. Combined with the sibling routing, exit conditions, and the do-not-start-another-run warning, an agent has everything needed to call this 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 50%: run_id has a solid schema description (and the description reinforces its role), but api_url is effectively undocumented. The description's guidance about template_id/saved_document_id concerns return values rather than input parameters, so it does not compensate for the api_url gap. Baseline 3 fits.

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 (check) plus resource (quick-schema run_id) and a key behavioral constraint ('once without waiting'), which cleanly distinguishes it from wait_for_quick_schema_creation. An agent can tell this is the non-blocking poll variant 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?

Explicit routing: if processing, 'call again later or use wait_for_quick_schema_creation', and an explicit exclusion — 'Do not start another schema-creation run just to check status.' Both the alternative and the anti-pattern are named, 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/idempotent/openWorld, and the description adds behavioral context those cannot: pages are snapshots, cursor is opaque and must not be constructed, refresh requires re-fetching and deduplicating by document ID, and a null cursor does not signal task completion. This is exactly the kind of subtle, non-structured behavior the description should carry.

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 action, then pagination, then completion routing, then refresh/dedup — a logical order. It is dense and every sentence carries information, but the final 'This returns a page, not a complete export' restates the opening scope somewhat, costing a little tightness.

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?

An output schema exists, so return shapes need not be spelled out, yet the description still orients the agent on key fields (documents[].id, extraction_data, next_cursor). For a paginated, read-only inspection tool the description covers invocation, pagination, refresh, and completion checks thoroughly.

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 75% and already documents limit (1-100, default 25), cursor (opaque, never construct), and task_id. The description reinforces how cursor works in practice ('same task_id', 'omit cursor to refresh'), adding operational meaning beyond the schema fields, though limit/task_id semantics add little new.

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+resource (inspect a page of documents for a task_id) and immediately scopes it as one page rather than a full export. It distinguishes itself from siblings by naming fetch_document_result, fetch_json_results, download_results as consumers of the IDs it returns, and wait_for_task_extraction as the completion authority.

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 ('including while processing'), how to paginate (pass next_cursor as cursor with the same task_id), how to refresh (omit cursor), and where to go for completion status (wait_for_task_extraction). It also warns that next_cursor null ends the snapshot, not processing — a genuine usage pitfall removed.

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/idempotent/openWorld, and the description stays consistent with them ('does not create or modify templates'). It adds genuine behavioral context beyond annotations: system templates are discovery-only, MCP cannot add them to the team or use their IDs directly, and when authorized schema creation is the fallback path.

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 default behavior, then layers routing guidance and constraints. Every clause carries information, though the dense run of conditional instructions (auto-detection, quick-schema fallback, system-template caveat) is packed tightly for a small tool.

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?

Output schema exists, so return-value explanation is unnecessary, and the description fully covers what an agent needs: selection workflow, the summary/full distinction, system-template limitations, and the no-match fallback. Complete for this tool's role as the entry point to the extraction workflow.

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 schema already documents view (summary vs full) and include_system fairly fully. The description reinforces with usage-oriented meaning ('Use view full to inspect schema and prompts', include_system adds discovery-only templates), but mostly restates rather than introducing new 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?

States a specific verb+resource ('Discover extraction templates') plus scope ('defaults to compact summary view with team templates only'). Immediately distinguishes it from the sibling extraction/creation tools by framing it as discovery only, ending with 'This tool does not create or modify templates.'

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 logic: prefer a matching active team template and pass its id as template_id to extraction tools; if none matches, omit template_id for auto-detection or use start_quick_schema_creation when schema creation is authorized. It names specific alternatives and the conditions that select them.

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

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

Annotations already mark this as non-read-only and non-idempotent, and the description adds substantial context beyond them: credits are consumed, submission is confirmed but not success, a recovery task_id should be reused rather than re-uploading, and the returned auto_approve echoes the request rather than backend approval status.

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 behavior is front-loaded in the first sentence and each subsequent clause carries distinct information (follow-ups, credits, timeout recovery, auto_approve). It is dense and semicolon-chained, which slightly hurts scanability, but little 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?

For an async submission tool with annotations and an output schema already present, the description covers the async contract, downstream tool chain, cost, failure/recovery path, and the non-obvious auto_approve caveat. Nothing an agent needs to call it correctly is missing.

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 already 86%, so most parameters are self-documenting, but the description adds interpretation the schema does not: auto_approve=false triggers human review that MCP cannot perform or approve, and the echoed value is not approval status. It adds useful nuance above the baseline.

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 clause states a specific verb, resource, and scope: 'Start background extraction of one local file.' It also distinguishes itself from the async siblings by stating it returns task_id 'without waiting for processing,' making it clearly distinct from wait_for_task_extraction and extract_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?

It maps the downstream workflow explicitly (wait_for_task_extraction, then fetch_document_result or download_results, with get_task_results for partials) and gives a recovery rule on timeout. It does not directly compare against extract_file/extract_folder, so the choice among the start/extract family is left partly implicit.

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 annotations: 10 concurrent upload cap, non-blocking return of one task_id per confirmed upload, credit consumption, cancellation only preventing new uploads while submitted tasks may still run, unstarted entries meaning not uploaded, and the auto_approve/human-review limitation that MCP cannot approve. These are exactly the operational traits 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?

Front-loads purpose and return behavior, then packs concurrency, credits, retry, and cancellation caveats into few sentences with no filler. Dense but each sentence carries operational weight; minor strain from cramming several caveats into the tail.

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?

An output schema exists so return values need not be explained, yet the description still notes the async task_id-per-upload contract. Combined with annotations and near-complete schema coverage, an agent has everything needed to invoke this 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 already 86%, so baseline is 3, but the description adds real meaning for auto_approve (default true, false triggers human review MCP cannot perform) and reinforces folder_path/credit implications. It does not clarify split, template_id, or pdf_password beyond what the schema already documents.

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 ('Start background extraction') plus the exact scope: supported files directly inside a local folder, skipping directories and subfolders. The nonrecursive local-folder framing distinguishes it from sibling file/folder extraction tools without needing the schema open.

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 an explicit follow-up workflow ('use wait_for_task_extraction for each task, then fetch or download results using its document IDs') and a retry precondition (inspect failed entries and recovery IDs before retrying). It does not explicitly contrast with extract_folder or start_file_extraction, so routing among the extraction starters still takes some 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 write/non-idempotent/open-world, and the description adds real behavioral context beyond them: credit consumption, the duplicate-work hazard, the fact that MCP does not create upload batches, and what a completed run returns (template IDs and saved document IDs) that should be inspected before another extraction.

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 is front-loaded in the first clause and every sentence carries information (output routing, return contents, conditional params, duplicate warning). It is dense and clause-heavy, 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?

For a write tool with an output schema, the description covers the trigger condition, the cost implication, the correct follow-up tools, and the idempotency hazard. Nothing an agent needs to invoke this correctly is missing.

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 83%, so the baseline is 3, and the description adds genuine meaning for two parameters: upload_batch_id and source_upload_id are only supplied by an external batched-upload workflow, and only one local file is accepted. It does not add detail for file_path, folder_id, or pdf_password 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?

States a specific verb and resource ('Upload one local file to automatically create extraction schemas/templates') and explicitly distinguishes its output from sibling artifacts ('not an extraction task_id or export_job_id'). An agent can separate this from start_file_extraction and the export tools without opening 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?

Gives the triggering condition ('use when the user authorized schema creation, which may consume credits') and routes the agent to the correct polling siblings (get_quick_schema_creation / wait_for_quick_schema_creation). It also warns against re-invocation ('Starting again can create duplicate work').

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/openWorld/idempotent, and the description adds behavior they cannot convey: the 60000ms default covers polling retries and is not the full MCP call, timeouts are recoverable (job id remains valid), and failed/expired/unsupported jobs surface errors with recovery details. That is real operational context beyond the structured hints.

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 sentences, all earning their place, with the what-it-does and what-it-does-not-do front-loaded before the completion workflow and timeout recovery. Slightly dense with three distinct guidance blocks, but nothing is redundant 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?

An output schema exists so return values need no explanation, and the description still covers the complete lifecycle an agent needs: prerequisite job id, wait semantics, success next step, timeout recovery, and failure modes. Nothing required to invoke or recover correctly is missing.

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% (api_url undocumented) and the two described parameters already carry their own schema text, but the description clarifies the semantics of wait_timeout_ms as a polling-window budget including retries rather than a hard call timeout — meaning the schema alone does not convey.

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 (wait) on a specific resource (an existing export_job_id) and explicitly negates two adjacent behaviors: it does not submit an export and does not download its file. That negative framing separates it cleanly from start_file_extraction and download_export_job without needing their 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?

Gives the full workflow: call this to wait, then use download_export_job to save the artifact. It also covers the non-obvious branch — on polling timeout, retain the export_job_id and call get_export_job or this tool again rather than submitting another export, which directly prevents duplicate-job misuse.

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 safe/idempotent read behavior, but the description adds substantial context beyond them: terminal failure is returned in result, so a successful tool call doesn't imply success; the agent must inspect status and failed_documents. It also discloses SDK polling defaults (5s/300 attempts) and the timeout/resume 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?

Front-loaded with the wait condition and terminal states, then progressively adds the failure caveat, return values, and polling guidance. Every sentence carries actionable information with 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?

An output schema exists, yet the description still usefully notes the return of template IDs and document IDs. Combined with the polling and timeout guidance, nothing an agent needs to call and correctly interpret this tool is missing.

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 75%, so the schema already documents run_id and poll_interval formats. The description nonetheless adds real meaning for max_poll_attempts (set lower to fit client tool timeout, resume with same run_id), which goes beyond the schema's terse wording.

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?

Specific verb+resource: waits on an existing quick-schema run_id until a terminal status. It clearly distinguishes itself from sibling start_quick_schema_creation and get_quick_schema_creation by naming the run_id produced by the starter.

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 conditions plus failure-handling guidance: choose a smaller max_poll_attempts for short client timeouts, and on timeout re-check or wait on the same run_id rather than starting a new run. It routes the agent away from the wrong alternative action (starting another run).

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 readOnlyHint/idempotentHint/openWorldHint annotations by disclosing terminal-state semantics (completed and partially_completed succeed; failed and insufficient_credits error), the warning that partial completion is not success for every document, and that SDK backoff/retries mean the poll window is not a strict wall-clock deadline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the return contract and the success/failure states, then layers downstream routing, polling caveats and the review exclusion. Every sentence carries operational information; none 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?

Covers outcome semantics, error modes, retry-on-timeout behavior, downstream tooling and an explicit non-capability, and it need not explain return values since an output schema exists. An agent has everything needed to invoke and interpret this call 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 schema already documents task_id, poll_interval and max_poll_attempts at 75% coverage, and the description largely restates the defaults (2s, 3 attempts). It does add genuine meaning by explaining that backoff makes the effective delay larger than poll_interval, but the api_url parameter is left entirely unexplained.

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+resource ('Wait for an existing extraction task_id') and immediately scopes the return value ('returns status and document_ids, not extracted data'), which separates it from get_task_results, fetch_document_result and download_results without opening 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?

Explicitly routes the agent downstream ('Use fetch_document_result or download_results with the returned document IDs'), handles the timeout case ('call again with the same task_id rather than uploading again'), and states an exclusion ('does not approve documents awaiting human review'). This is when/when-not/alternatives guidance in full.

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