DocImprint Document Intelligence

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral context: 'Free — no credits consumed' clarifies that the operation itself has no cost, which is critical for a quota tool. It also discloses the response structure precisely, including the status field with possible values.

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 well-structured and front-loaded: it opens with the core purpose, then adds the no-credits detail and usage timing, followed by a clear return block and example prompts. Every section earns its place, and the length is appropriate.

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

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

Given the tool's simplicity (no parameters) and the presence of formal annotations plus a detailed return schema in the description, the description covers all essential context: purpose, usage scenario, return payload, and example queries. It is complete for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there are no parameter semantics to explain. The description correctly omits parameter details; the empty schema makes this self-evident. Baseline of 4 applies due to 0 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 clearly states the tool's function with a specific verb and resource: 'Get current credit balance and plan details for your API key.' It distinguishes from sibling tools by focusing on account/quota status, and specifies the return contents (plan tier, billing period, usage breakdown).

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 explicitly instructs when to use the tool: 'Check this before running credit-consuming operations (extract, summarize, etc.) to avoid QUOTA_EXCEEDED errors.' This provides clear contextual guidance, and the example prompts reinforce typical usage. It does not need alternatives since no competing tool exists.

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 and idempotentHint, but the description adds meaningful behavior beyond that: it is free ('no credits consumed'), scoped to bundles owned by the API key, and returns a signed action receipt binding the lookup to the manifest. This gives the agent crucial context about side effects and constraints that annotations alone do not cover.

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 core purpose, then usage guidance, alternatives, return fields, and examples. While the return-field list duplicates the output schema, it is presented compactly and every sentence contributes actionable information. It is a bit long but not bloated.

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 one parameter, an output schema, and strong annotations, the description still adds substantial value: cost, ownership, alternatives, receipt behavior, and example prompts. It fully equips the agent to decide when to invoke and what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully documents the only parameter (bundle_id) with a clear description and example, so the schema carries the weight. The description repeats this via example prompts but does not add new semantic details beyond what the schema already provides. 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?

The description opens with a specific verb+resource: 'Retrieve metadata for an evidence bundle (ev_...)' and clearly distinguishes this from bundle.verify by stating it is for quick status/metadata lookups while verification is for deep cryptographic integrity checks. This unambiguously defines the tool's scope.

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

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

It explicitly enumerates use cases ('checking if a bundle is complete, finding its notarization status, or viewing retention/legal hold info') and names an alternative for a different job ('use bundle.verify instead'). It also references companion tools (receipt.list, receipt.verify) for further actions, giving clear when-to-use guidance.

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 adds substantial behavioral context beyond the annotations: idempotency (returns existing attestation if already notarized), gas costs, permanence of the on-chain record even if the bundle is purged, and the signed action receipt returned. No contradictions with annotations; idempotentHint is consistent with the stated idempotent 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?

Though detailed, the description is well-structured with clear sections (PREREQUISITE, NOTE, Returns, Example prompts). Every sentence conveys necessary information for a high-stakes, gas-costly blockchain operation, and it is front-loaded with the core purpose. The length is justified by the tool's complexity.

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

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

Given the tool involves an on-chain write with financial cost and permanent records, the description covers all essential context: when to use, prerequisites, cost implications, permanence, output structure, and example prompts. The output schema is also present, so the explicit return field listing is a bonus. This description is fully complete for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully describes the bundle_id parameter with 100% coverage, including format, example, and status requirement. The description reinforces this by embedding the prerequisite ('Bundle status must be complete') and using the example in prompt suggestions, adding marginal value 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 clearly states the tool's function: notarizing an evidence bundle on-chain by writing its SHA-256 manifest to the blockchain. It also differentiates from sibling tools like bundle.verify by emphasizing the on-chain, permanent timestamping use case.

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 the tool ('when you need an immutable on-chain timestamp') and when not to ('For quick integrity checks without on-chain cost, use bundle.verify instead'). It also specifies a prerequisite (bundle must be 'complete', check with bundle.get), giving clear operational guidance.

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 idempotentHint, and the description adds significant behavioral context: it is free (no credits consumed), checks the bundle is owned by the API key, enumerates specific integrity checks, and discloses that it returns a signed action receipt. This goes well beyond the annotation hints and adds useful operational details.

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 well-structured with purpose, usage, return value, and examples. It is longer than minimal but each section earns its place. The Returns block may be redundant with the existing output schema, but it still aids quick comprehension without being overly verbose.

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

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

The description covers when to use, alternatives, cost, ownership, what is verified, and receipt handling. Combined with rich annotations and an output schema, it leaves no major operational gaps for an agent to correctly select and invoke this tool. The context signals indicate high schema and annotation richness, and the description completes the picture.

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 for the single parameter bundle_id is 100%, including type, description, and an example. The description does not add parameter-specific semantics beyond the schema, so the baseline score of 3 is appropriate. The schema already carries the full burden for 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 specifies a clear verb and resource: 'Verify the cryptographic integrity of an evidence bundle', and enumerates exact checks (manifest hash, EIP-191 signature, R2 artifact hashes). It also distinguishes itself from sibling bundle.get, which is for quick metadata lookups without full verification, making differentiation explicit.

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

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

The description provides explicit usage guidance: 'Use when you need to confirm a bundle has not been tampered with' and contrasts it with 'For quick metadata lookups (without full crypto verification), use bundle.get instead.' It also gives concrete example prompts that demonstrate when and how to invoke the 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?

Beyond the annotations, the description discloses that indexing is async, returns a job_id to poll, and provides a signed action receipt. It also mentions the requirement for bundle status and ownership. No contradiction with annotations.

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

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

The description is well-structured with a clear opening, usage note, return contract, and examples. It is longer than minimal but every section adds value—prerequisites, async behavior, receipt handling, and invocation examples. Not all sentences are essential, hence a 4.

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

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

Given the tool's async nature and return of job_id/receipt, the description covers the full workflow: how to invoke, what to do after (poll), prerequisites, and return structure. It also aligns with sibling tools (job.status, receipt.verify, collection.search) and provides example prompts.

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 baseline applies. The description reinforces parameter usage through examples and prerequisites but does not add substantial meaning beyond the schema descriptions, which already include examples and constraints.

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

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

The description starts with a specific verb and resource: 'Add an evidence bundle to a collection and trigger async vector indexing.' It clearly distinguishes from siblings like collection.create (create collection), collection.search/ask (query), and bundle.get/receipt.verify.

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 explicitly states when to use it ('Use after collection.create'), what happens after indexing (searchable via collection.search and collection.ask), and gives prerequisites (bundle complete, collection owned). It also tells the agent to poll job.status, providing a clear workflow with alternatives.

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 idempotentHint, so the description's added context (synthesis process, citation behavior, return structure) is valuable. It also warns that collection must be populated first. It doesn't cover failure modes or rate limits, but for a read-only retrieval tool this is adequate.

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 moderately long but well-structured: main purpose, usage guidance, prerequisite, return type, and examples. It is front-loaded with the core verb and resource. Some redundancy between the first sentence and the 'Use when' clause, but overall 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?

The description is highly complete for a RAG tool. It covers what it does, when to use it, how it differs from alternatives, prerequisites, and the exact return structure. The output schema already exists, so return values are documented, and the description reinforces them with an example structure.

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%, with each parameter (question, max_chunks, collection_id) having a clear description and example. The description text does not add new parameter-level semantics beyond the schema, but the example prompts illustrate question phrasing. 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?

The description clearly states the tool performs RAG over a document collection to answer questions with source-attributed synthesis. It explicitly distinguishes itself from collection.search (raw chunks) and url.qa (single-document Q&A), making its purpose unambiguous.

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

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

It provides explicit when-to-use guidance ('Use when you need a direct answer grounded in your collection documents') and names specific alternatives with different use cases. It also includes a prerequisite about populating and indexing the collection, which is essential for correct usage.

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 readOnly/idempotent/destructive, but the description adds valuable behavioral details not in annotations: it's free (no credits), collections start empty, indexing is async, and it returns a specific object shape with collection_id. This goes beyond the structured fields.

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

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

The description is well-structured with a clear opening, a note about async indexing, return format, and example prompts. While longer than the minimal example, each section adds practical value and the structure is 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 simple creation tool, the description covers purpose, usage, workflow, return schema, and examples. It mentions related sibling tools appropriately and leaves no major operational 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?

The schema fully describes the 'name' parameter with an example. The description reinforces it with prompt examples and mentions 'named' but doesn't add new technical constraints. Given 100% schema coverage, the baseline of 3 applies.

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

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

The description opens with a specific verb+resource: 'Create a named document collection' and defines its purpose for cross-document semantic search and RAG-based Q&A. This clearly distinguishes it from sibling operations like collection.search, collection.ask, and collection.add_document.

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

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

It explicitly states when to use: 'Use when you want to group related evidence bundles for unified search or question answering.' It also clarifies the workflow by noting collections start empty and that documents must be added via collection.add_document, with indexing async. This gives clear context, though it doesn't enumerate exclusions like when not to use.

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 idempotentHint, and the description adds valuable context: it is free and consumes no credits, returns a specific structure, and supports pagination. This goes beyond the annotations without contradicting 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?

The description is well-structured and front-loaded with the core purpose, but the three example prompts are somewhat redundant and could be trimmed for tighter conciseness.

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

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

The description covers all important aspects: what is listed, ownership scope, cost, usage context, pagination, and return format. It is self-contained and sufficient for an agent to decide when and how to invoke the 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?

The input schema describes both parameters (limit and offset) with examples, so schema description coverage is 100%. The description only mentions 'Supports pagination with limit and offset,' which adds minimal value 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 clearly states 'List all document collections owned by your API key' using a specific verb and resource, and it distinguishes itself from sibling tools like collection.search and collection.ask by emphasizing listing all collections rather than searching or asking.

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

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

It explicitly says 'Use before collection.search or collection.ask when you need the collection ID,' which provides clear context for when to use this tool and names alternatives. It also mentions free usage and pagination support.

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 idempotentHint, so the description adds value by disclosing that the operation is 'Free — no credits consumed' and that async indexing must complete before results appear. This clarifies real-world behavior beyond the safety 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?

The description is well-structured with clear sections: purpose, usage guidance, prerequisite, return format, and example prompts. It is front-loaded with the main purpose and includes no filler. Every sentence contributes to understanding the 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?

The description covers all necessary context: purpose, usage, prerequisites, return format, cost, and examples. Given the tool's moderate complexity and the presence of an output schema, this is fully self-contained and leaves no major gaps for an agent to misuse.

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 all parameters (collection_id, query, limit) are already documented with descriptions and examples. The description adds example prompts that illustrate query phrasing but does not change the fundamental meaning of any parameter. 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?

The description clearly states 'Semantic (vector) search across documents in a collection' with a specific verb (search) and resource (documents in a collection). It also distinguishes itself from sibling tool collection.ask, which provides synthesized answers rather than raw chunks.

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: 'Use when you need raw matching chunks from a collection.' Directly names the alternative: 'For a synthesized cited answer from the same context, use collection.ask instead.' Also provides a prerequisite about indexing completion and polling job.status.

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 idempotentHint, and the description adds substantial behavioral context: AI model quality, citation-level evidence, return structure with statuses and confidence, and the `truncated` flag. It also clarifies that max_tokens truncates input (in schema) but adds the return-level `truncated` indicator. No contradictions with annotations.

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

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

The description is well-structured and front-loaded: a clear purpose sentence, usage alternatives, workflow, return shape, and example prompts. Every section adds value without redundancy. It is longer than a minimal description but all content is used.

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 tool with 3 parameters and a structured output, the description covers all necessary context: when to use, how to use, what it returns, and examples. The return schema is shown in the description, so the agent fully understands behavior before invoking the tool. Given the existing output schema, this is complete.

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%, with each parameter (text, claims, max_tokens) already described in detail. The description does not add new parameter semantics beyond the schema, only example prompts that illustrate usage rather than parameter meaning. Baseline of 3 is appropriate because the schema carries the full load.

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 and resource: 'Verify a list of factual claims against document text.' It also distinguishes from siblings by mentioning 'citation-level evidence' and explicitly comparing to url.qa and collection.ask for different use cases.

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 (validate specific assertions after extraction), when not to use (open-ended questions → url.qa; multi-document → collection.ask), and gives a typical workflow from extraction to checking claims. This is clear guidance with named alternatives.

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 idempotentHint, so the description doesn't need to restate them. It adds useful context about using a 'quality AI model with retry logic' and details the return structure with confidence levels and citations, which goes beyond annotation coverage.

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 moderately long but well-structured, with clear sections for purpose, usage, schema format, output, and examples. Every section earns its place given the tool's complexity, though it could be tightened slightly without losing value.

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

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

The description covers usage context, alternatives, parameter examples, and explicitly describes the return object. For a complex tool with an output schema, this is comprehensive enough for an agent to select and invoke it correctly, though it doesn't address potential errors or edge cases.

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 baseline is 3. The description provides a concrete schema format example and example prompts, but the schema descriptions already explain the parameters well. The added value is marginal—mainly illustrative rather than clarifying 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?

The description clearly states the tool extracts typed fields from document text using a caller-defined schema. It distinguishes itself from sibling tools by mentioning schema-driven extraction and explicitly contrasts with document.parse_invoice and document.summarize.

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 guidance is provided: 'Use when you need specific data points from a document rather than full text,' and alternatives are named: 'For invoices with known fields, document.parse_invoice may be simpler. For general summarization, use document.summarize instead.'

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 idempotentHint=true, so the safety profile is known. The description adds value by disclosing the return format ({ pages, text } with Markdown tables) and input base64 encoding requirement, which is useful behavioral context beyond the annotations.

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

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

The core description is concise and front-loaded, but the inclusion of three example prompts adds length. While these examples are useful, they could be trimmed without losing essential information. Overall, it remains efficient and well-structured.

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

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

Given the simple tool with clear input schema and output schema (signal indicates has output schema: true), the description is complete. It explains when to use, what to expect in the output, and provides examples, covering all necessary context.

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 both parameters fully. The description does not add significant parameter semantics beyond what the schema provides, such as reiterating base64 encoding but without new detail.

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 extracts tables and forms as Markdown from PDFs or images, using a specific verb and resource. It also distinguishes from sibling tool document.extract_text by noting it's for plain prose documents, providing clear differentiation.

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

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

Explicitly specifies when to use the tool: 'Use when the document contains structured tabular data such as financial statements, data sheets, or forms.' It also names the alternative tool (document.extract_text) for prose documents, giving clear usage guidance.

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 idempotentHint=true, covering the safety profile. The description adds value by specifying the return shape ('Returns: { pages: number, text: string }') and indicating OCR capability for images. It does not contradict annotations.

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

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

The description is well-structured, starting with the core action, followed by usage context, an alternative, the return format, and example prompts. The example prompts are slightly redundant but aid understanding. It is not overly verbose.

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 tool with 2 parameters and full schema coverage, the description covers purpose, usage, output shape, and an alternative tool. It does not mention error handling or size limits, but the schema includes the size limit, making the overall guidance adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% coverage with descriptions and examples for both parameters. The description does not add significant parameter details beyond what the schema already states, so the baseline score of 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?

The description clearly states a specific verb+resource: 'Extract plain text from a PDF or image (base64-encoded).' It also distinguishes itself from the sibling tool url.extract by explicitly noting that URL-based documents should use that alternative, which avoids ambiguity.

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

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

The description provides explicit when-to-use guidance: 'Use when you need raw text for downstream AI analysis (summarization, claim checking, structured extraction).' It also names a concrete alternative for public URLs, fulfilling the when-not-to-use condition.

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?

Even with readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral detail: it uses a quality AI model, returns confidence levels and citations, and shows the exact return structure. This goes well beyond the annotation-only baseline.

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 well-organized: purpose, usage guidance, return format, and example prompts. Every section adds value, and it remains concise despite the rich content, earning a top score.

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

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

Given the tool's complexity, the description fully covers purpose, usage, output schema (via the return structure), and examples. Combined with complete parameter schema and annotations, nothing is left ambiguous for the AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% coverage with detailed descriptions and examples for both parameters. The description does not add param-specific semantics, so the baseline of 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?

The description clearly states it parses receipts/invoices into structured fields, specifies the extracted data (line items, totals, merchant info), and distinguishes itself from document.extract_text. The verb and resource are specific and unambiguous.

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

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

Explicitly says 'Use when you need to extract line items, totals, and merchant info from financial documents' and directs users to document.extract_text for general text. Example prompts further clarify appropriate usage scenarios.

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 idempotentHint, lowering the bar. The description adds useful behavioral context beyond annotations: 'max_tokens' truncates input not output, and the return format includes 'truncated' and 'strategy' fields, describing how the tool handles long documents.

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 core purpose and usage guidance. It is somewhat long due to the return structure and example prompts, but every section adds value. It remains well-organized and avoids unnecessary words.

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

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

The description is complete for this tool: it provides workflow, alternatives, return structure, and example prompts. The presence of an output schema and annotations fills remaining gaps, so the description needs no additional context.

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 baseline is 3. The tool description repeats the schema's parameter descriptions but does not add significant new meaning; example prompts and return format are helpful for overall usage but not parameter-level semantics beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Summarize document text into a prose summary and key points with citations.' It clearly distinguishes from siblings by noting 'For single-sentence Q&A, use url.qa instead' and 'For extracting specific fields, use document.extract_structured.'

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 guidance is provided: 'Use after document.extract_text or url.extract when you need a condensed understanding of a long document.' It also states alternatives and a typical workflow, making the usage context 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: it is a polling endpoint, free with no credits consumed, completed jobs include bundle_id or result_json, and it details status values and progress fields. This provides a full picture of how the tool behaves at runtime.

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 moderately sized but well-structured, with a clear explanation, a return format block, and example prompts. Minor redundancy exists (bundle_id mentioned twice), but overall it is organized and each section serves a purpose.

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

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

Given the tool's simplicity, the description is thorough: it covers usage context, polling behavior, cost, return structure, and state transitions. The output schema is present, but the description independently explains the fields and statuses, making the tool fully understandable without external references.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers the single parameter (job_id) with a description and example. The description does not add additional parameter-specific semantics beyond the schema, so 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?

The description clearly states the tool polls the status of an async job, listing specific job types (extract, indexing, batch). It distinguishes itself from sibling tools by focusing on job status rather than data extraction or collection management, making its purpose unambiguous.

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

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

The description explicitly tells when to use the tool: after collection.add_document or async extract, and to poll in a loop until complete or failed. It also mentions when jobs are created (POST /v1/extract with webhook, or add_document), and provides example prompts, giving clear usage context and no misleading alternatives.

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 read-only and idempotent, and the description adds 'Free — no credits consumed' which is a cost behavior not captured by annotations. It also clarifies that receipts are scoped to the caller's API key ('owned by'), an access control detail. This goes beyond the structured fields, though it stops short of discussing error conditions or rate limits.

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 tightly written: a one-sentence purpose, a one-sentence usage context, a compact return structure, and three example prompts. Every sentence earns its place, and the structure front-loads the core purpose before adding workflow details.

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 a read-only, idempotent annotation profile, a full parameter schema, and an output structure explicitly described in the text. The description covers purpose, when to use it, behavioral quirks (free, owned by API key), and the return format. For this simple list operation, the context is complete enough for an agent to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters (bundle_id, limit, offset) are already described in the input schema with examples, so the schema covers 100% of the parameter semantics. The description doesn't add any parameter-specific syntax or format details, but it does provide example prompts that reference bundle_id. Given the high schema coverage, a baseline score of 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?

The description opens with 'List signed action receipts...' which clearly states the verb and resource, scoped to 'an evidence bundle owned by your API key.' It distinguishes from sibling receipt.verify by noting that this tool lists receipts while verification is a separate step. This is a specific, well-differentiated purpose.

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

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

It explicitly says 'Use after bundle.get, bundle.verify, bundle.notarize, or collection.add_document' to audit which agent actions were bound to which manifest hash, providing clear when-to-use guidance. It also directs the user to pass a receipt_id to receipt.verify for independent verification, effectively naming the alternative for the next step.

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 idempotentHint, so the safety profile is known. The description adds valuable context: it is free, it checks two distinct conditions (signature validity and manifest currency), and the output includes a 'tampered' string array that flags any altered fields. This goes beyond the annotations without contradicting 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?

The description is well-structured: it opens with the core purpose, then explains the verification logic, lists the return fields in a compact JSON shape, and ends with two example prompts. While a bit lengthy, every sentence carries useful information and the structure aids quick comprehension.

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

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

The description effectively includes an output schema through the Returns block, covers the input parameter and its origin, explains the verification semantics, and provides example user prompts. Given the tool's moderate complexity and the presence of an output schema, the description is complete and leaves no major gaps for an agent to successfully invoke it.

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 has 100% coverage with a description and example for receipt_id. The description further enriches meaning by explaining that the receipt ID is returned by specific sibling tools and appears in the format rcpt_..., which helps the agent map the parameter to real-world usage beyond the bare 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 uses the specific verb 'verify' and identifies the exact resource ('signed action receipt') with the rcpt_ prefix. It distinguishes this tool from siblings by explaining that it proves both signature authenticity and current manifest match, which clearly differentiates receipt.verify from bundle.verify and other verification-like tools.

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 explicitly states when to use this tool ('Use for third-party audit of an agent's prior actions'), names all tools that produce the receipts (bundle.get, bundle.verify, etc.), and adds a cost-related guideline ('Free — no credits consumed'). This gives clear, actionable context for when this tool is appropriate.

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 the description adds behavioral nuance: lean mode, no evidence bundle stored, no bundle_id returned, and final_url after redirects. It also restricts to public HTTPS URLs, which is useful context beyond the schema.

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

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

The description is front-loaded with the core function, then provides alternatives, return structure, and example prompts. It is well-structured, with each section earning its place and no 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?

For a simple single-parameter read-only tool, the description covers purpose, usage boundaries, return format, and example prompts. With output schema and annotations present, nothing critical 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 covers the single url parameter with a description and example (100% coverage). The description reinforces the HTTPS requirement and provides example prompts, but adds little else beyond what the schema already provides.

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 verb+resource: 'Fetch a public HTTPS URL and return extracted text and page metadata.' It distinguishes from sibling tools by naming alternatives for summaries, Q&A, translation, and file uploads, making the tool's unique role explicit.

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 directs when to use this tool vs alternatives: 'Use url.summarize for summaries, url.qa for Q&A, url.translate for translation, document.extract_text for base64 file uploads.' It also notes the lean mode with no bundle storage, implying a lightweight use case.

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=true, while the description adds behavioral details such as 'Lean mode — no bundle stored' and the 'truncated' field in the return value, indicating potential truncation. This goes beyond annotations, though it omits failure modes or rate limits, so not 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?

The description is well-structured with a clear action statement, usage guidance, return format, and example prompts. It is front-loaded with the core purpose and every sentence adds value. No wasted words.

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 straightforward fetch-and-answer tool, the description covers: what it does, when to use it, alternatives, return value structure, and example invocations. Output schema exists, but the description still explains the return fields. No significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level details beyond the schema, but it includes example prompts that illustrate parameter usage. The schema already explains max_tokens truncation behavior.

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 a specific verb and resource: 'Fetch a public HTTPS URL and answer a specific question about its content.' It differentiates from siblings by explicitly naming url.summarize and collection.ask as alternatives, and adds 'Lean mode — no bundle stored' to set it apart.

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 usage guidance: 'Use when you have a precise question about a web page.' It also gives clear exclusions and alternatives: 'For a broad summary, use url.summarize. For multi-document Q&A, use collection.ask instead.' This is high-quality differentiation.

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. The description adds useful context: 'Lean mode — no bundle stored' clarifies lack of persistent side effects, and the return shape is described. It doesn't mention rate limits or error handling, but these are less critical for a read-only fetch.

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 appropriately sized: first sentence states the core function, then usage guidance, return format, and example prompts. Every sentence earns its place with no filler or redundancy.

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

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

Given two parameters fully explained in the schema, annotations covering read-only and open-world, and an output schema, the description provides sufficient context: it explains when to use it, what it returns, and how to formulate prompts. It is complete for the tool's complexity.

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%, with both 'url' and 'max_tokens' well-documented. The description provides example prompts that illustrate usage but adds no new parameter semantics beyond the schema. Baseline 3 applies.

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 action ('Fetch a public HTTPS URL') and output ('prose summary with key points'), clearly distinguishing it from sibling tools url.extract and url.qa. It also mentions the return structure.

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 the tool ('Use when you need a condensed understanding of a web page') and provides direct alternatives: 'For raw text, use url.extract. For asking a specific question about a page, use url.qa.' This is clear and actionable.

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 meaningful behavioral context beyond that: 'Lean mode — no bundle stored' (clarifies side effects), 'public HTTPS URL' (constrains input), and the return shape including 'truncated' (indicates possible content truncation). This goes beyond simply restating the annotations, though it does not cover every possible behavior like rate limits or auth, which is acceptable given the read-only nature.

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 well-structured and reasonably sized: core function in the first sentence, followed by behavior, usage guidance, return shape, and examples. Every sentence contributes value, and the examples are useful for an agent. It is slightly longer than the minimal two-sentence example, but the extra content (alternatives, return structure, examples) is justified.

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

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

Given the tool's moderate complexity (3 parameters, output schema present, annotations present), the description is quite complete. It covers what the tool does, when to use it, an alternative, key behavioral traits, and return structure. The only minor omission is explicit mention of max_tokens, but the schema fully documents that, so the overall completeness is high.

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%, with all three parameters (url, max_tokens, target_lang) documented with types, descriptions, and examples. The description itself does not add additional parameter semantics beyond what the schema already provides, so the baseline of 3 applies. The example prompts indirectly illustrate how to use url and target_lang, but this is marginal additional 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 description clearly states the tool's function: 'Fetch a public HTTPS URL and return its content translated into a target language.' It uses a specific verb ('fetch', 'return') and resource ('content translated'), and distinguishes itself from the sibling url.extract by explicitly noting it provides raw untranslated text. This makes the purpose unambiguous.

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

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

The description gives explicit usage guidance: 'Use when you need to understand web content in a different language' and provides a concrete alternative for a different need: 'For extracting raw untranslated text, use url.extract instead.' This satisfies the when/when-not/alternatives criterion fully.

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