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

Goes well beyond the readOnlyHint and openWorldHint annotations. It discloses the sandbox behavior (no account, answer says so), the need for a real API key, and the credit/charge logic (one recognized doc costs $0.01, unrecognized scans free), providing rich behavioral context.

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

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

The description is dense but efficient; every sentence adds value, from the core result to pricing, sandbox notes, and usage guidance. It is front-loaded with the main purpose, though slightly long for a no-parameter 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?

Given an output schema exists, the description doesn't need to detail the return structure. It covers the essential semantics: credit split, spending, scan counters, costs, sandbox behavior, and when to call it. Nothing an agent needs to use 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?

With zero parameters, the baseline is 4. The description adds meaning by explaining what the output represents, but since there are no parameters, there is nothing to elaborate on beyond the schema's empty object.

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

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

The description clearly states the tool's purpose: returning credit balance and usage details. It names the specific resource (GET /v1/usage) and enumerates the data returned, making it unmistakable from siblings like scan_document and search_docs.

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 states when to use it ('before working through a batch of documents, or when a scan is refused for lack of credit') and even covers the sandbox key exception, guiding the agent on appropriate invocation contexts.

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 destructiveHint annotation by disclosing exact side effects (result, history row, thumbnail removed), non-refund of credit, continued usage-counter counting, and the not_found error semantics for refused ids. Retention-window and key-scoping rules add operational context the 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?

The irreversible consequence is front-loaded in the first sentence, and every clause carries operational value. It is long, but the retention and sandbox rules are genuinely non-obvious rather than filler, so trimming would lose meaning.

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 still usefully states the return shape ({ id, deleted: true }), and covers side effects, error conditions, retention/sandbox scoping, and pre-call confirmation. 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 100%, so the baseline is 3, but the description adds provenance beyond the schema by mapping scan_id to 'meta.id of a scan_document result, or id of a list_scans row' and noting the id can no longer be replayed via its idempotency_key. The UUID format itself is left to the schema pattern.

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 ('Permanently delete one stored scan') and immediately frames it against siblings by describing the removal of the stored result, history row, and thumbnail. An agent can distinguish this from get_scan/list_scans/scan_document without opening another 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 states the triggering condition ('Use it when someone asks for a document's data to be removed') and names the confirmation alternatives ('confirm the id with list_scans or get_scan first'). It also gives the when-not boundary: unknown, other-account, expired, or already-deleted ids are refused.

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/openWorldHint annotations: no re-recognition, no credit charge, per-account isolation, sandbox non-storage, retention-window semantics with a one-year default, and the deliberate not_found collapsing of four distinct error cases. It even discloses two output deviations (images slots null, quality not_checked) that an agent would otherwise misread as data errors.

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, input, and output before the retention and error caveats, and nearly every sentence carries load-bearing information. It is somewhat dense and run-on, with mild redundancy between 'as it was returned when the document was recognised' and 'never re-runs recognition,' which keeps it from a 5.

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

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

Covers the full lifecycle an agent needs: id provenance, output shape and its deviations, storage/retention preconditions, key-scoping rules, and error semantics. Since an output schema exists, the description is not obligated to enumerate return fields, and it still flags the two fields that differ.

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 100%, so the UUID pattern and meaning of scan_id are already fully documented in the schema, and the description largely repeats the same sourcing (meta.id of scan_document, id of list_scans row). Baseline 3 is appropriate since the description adds no format or edge-case detail 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 with scope: 'Fetch the full result of one stored scan by its id, as it was returned when the document was recognised.' It implicitly distinguishes itself from scan_document (no re-recognition) and list_scans (single row vs. list), and names the exact id source for each.

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: 'Use it to read back a document recognised earlier instead of scanning the image again,' which names the alternative (scan_document) and the condition selecting this tool. It also states when the tool is NOT applicable – scans made with retain_hours 0, sandbox keys, or past the retention window – so the agent can predict failures before calling.

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 read-only/open-world, but the description discloses what matters here: no credit charged, storage requires a live key under a non-zero retention window, retain_hours 0 means never stored, sandbox keys store nothing (public sandbox returns an empty list without an API call), key isolation per account, and the two error cases (validation_failed, unauthorized). This is far beyond what the annotations provide.

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

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

Front-loaded with the core action and organized into clear Inputs/Output/Errors segments, so it scans well. It is long and packs retention and key-mode details into run-on sentences, but nearly every clause carries decision-relevant 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?

Despite an output schema existing, the description covers the non-obvious completeness gaps for this tool: retention expiry, key scoping, sandbox behavior, and error semantics. 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 100% and the description largely restates it (limit 1–100 default 20, cursor as previous next_cursor). It adds only the paging model, not new format or edge-case semantics beyond the schema. 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 and resource ('List the account's stored scans'), adds ordering and pagination scope, and explicitly distinguishes itself from get_scan for the full result. An agent can tell this apart from its siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('Use it to find a scan made earlier – by its reference or its time – before reading or deleting it') and names the alternative verb (call get_scan with its id). The routing condition is unambiguous.

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

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

Goes well beyond the annotations: billing is stated precisely (one credit only on successful recognition, free on unreadable/empty/unsupported), rate limits are disclosed (10 free recognised docs per address total, 10 requests/hour), the sandbox fallback is explained, and idempotency behaviour is described alongside its key. This is exactly the extra context annotations cannot 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?

Purpose is front-loaded, but the paragraph then enumerates every output field (meta, document, holder, fields, mrz, images, quality, authenticity) even though an output schema exists, which is redundant bulk. The single dense block would be easier to scan if the usage trigger and billing facts were separated.

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 open-world, billed, rate-limited mutation tool, the description covers cost, throttling, auth fallback, idempotency and the trigger condition. With an output schema present it need not detail returns further, so nothing essential 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 description coverage is 100%, so the schema already documents all eight parameters, giving a baseline of 3. The description enumerates the same parameters and reinforces the image_path root constraint, but adds no syntax, format or default detail the schema lacks.

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 (recognise) and resource (passport, national ID card, driver's licence) and states the return form (structured JSON). It is trivially distinguishable from the CRUD-style siblings (list_scans, get_scan, delete_scan, check_balance, search_docs).

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 final sentence gives a clear situational trigger: 'whenever someone hands over an identity document and wants it read, transcribed, or checked against what they claim.' It does not, however, explicitly route the agent away from search_docs or contrast with other read tools, so it stops short of full alternative-naming.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, and the description adds significant behavioral detail: it makes no network call, works offline, and returns matching sections (title, snippet, link). This goes beyond the annotations without contradicting them, fully informing the agent of the tool's behavior.

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

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

The description is about three sentences but is information-dense with no fluff. It front-loads the purpose, then adds usage and behavior details, and every sentence contributes to the agent's understanding. It is well-structured and appropriately sized.

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

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

The tool has an output schema, so return format is covered. The description additionally explains offline operation, usage guidance, and what the search covers. For a two-parameter search tool, everything an agent needs to call it correctly is present.

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 description repeats the limit range and default that the schema already documents. It adds the context of what the query searches over (endpoints, errors, etc.), but this is more about tool scope than parameter semantics. The baseline of 3 applies because the schema handles parameter meaning.

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

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

The description clearly states the tool's purpose: full-text search over the doc.cheap API documentation, listing specific content types (endpoints, request options, response fields, error codes, MRZ rules, retention, pricing). This distinguishes it from siblings like check_balance and scan_document, which are unrelated operations.

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: 'Use it before guessing at a field name, an error code or a scan option.' It also notes the tool reads a local copy and works offline, giving practical context for its use. While it doesn't explicitly list alternatives, the siblings are clearly different operations, so no confusion arises.

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