api

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that it's free and consumes no credits, which reinforces safety. Also details return structure (plan tier, billing period, credits breakdown, status) with example 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?

Description is fairly concise with three paragraphs: purpose/usage, return structure, and example prompts. Could be tighter but front-loads key information. Example prompts add helpful context for agents.

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 zero parameters and a rich output schema described inline, the description is complete. It covers purpose, usage guidance, return format with field types and example statuses, and example queries. No gaps for a simple read-only 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?

No parameters in schema, so no param info needed. Baseline is 4 for zero parameters. Description adds value by explaining what the tool returns, fulfilling the purpose with no parameters to document.

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?

Description clearly states 'Get current credit balance and plan details for your API key' with specific verb 'Get' and resource 'quota'. Emphasizes it's free and no credits consumed, distinguishing it from credit-consuming siblings like document.extract 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?

Explicitly advises 'Check this before running credit-consuming operations to avoid QUOTA_EXCEEDED errors', providing clear when-to-use guidance. Includes example prompts demonstrating 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 true. The description adds 'Free — no credits consumed' and explains the signed action receipt binding, providing useful context beyond 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?

Well-structured: main purpose, usage guidance, return format, and example prompts. Every sentence contributes value without 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 one parameter and a detailed inline output schema, the description covers all necessary information: what it does, when to use, what it returns, and example prompts. No gaps.

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

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

Schema coverage is 100% with a detailed description of bundle_id. The description adds context that the bundle must be owned by the API key, which augments 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 states 'Retrieve metadata for an evidence bundle (ev_...) owned by your API key,' which is a specific verb and resource. It distinguishes itself from bundle.verify and receipt tools, making its purpose clear.

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 'Use for quick status/metadata lookups... For deep cryptographic integrity verification ... use bundle.verify instead.' Also mentions receipt.list and receipt.verify for the returned receipt, providing clear when-to-use and 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?

Description adds context beyond annotations: it mentions idempotency (returns existing attestation if already notarized), gas cost, permanence, and that it cannot be deleted. 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?

Description is well-structured and front-loaded, but slightly verbose with example prompts and a detailed return structure. Still, every sentence earns its place.

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 (one parameter), the description covers all necessary aspects: idempotency, prerequisites, costs, permanence, return structure, and related tools (bundle.verify, receipt.list, receipt.verify). It is fully self-contained.

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 baseline is 3. Description adds value by specifying the prerequisite (bundle status must be complete) and providing an example, which aids understanding beyond the schema's description.

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 that the tool notarizes an evidence bundle on-chain by writing its SHA-256 to the blockchain, creating a permanent record. It distinguishes from siblings by mentioning bundle.verify for quick checks without on-chain cost.

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 (immutable on-chain timestamp), when not to (use bundle.verify for quick checks), and provides prerequisites (bundle status must be complete) and caveats (costs gas, permanent record).

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?

Discloses that the operation is free (no credits consumed) and includes details of cryptographic checks performed. Annotations already indicate read-only and idempotent, and the description adds context about returning a signed action receipt. 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?

Well-structured with clear sections, including example prompts. While comprehensive, the description could be slightly trimmed without losing clarity, but it remains efficient and informative.

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 presence of annotations (readOnlyHint, idempotentHint) and a full output schema in the description, the tool definition is complete. It covers purpose, usage, parameters, return values, and example interactions. No gaps detected.

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?

Only one parameter (bundle_id) with 100% schema coverage. The description adds context by specifying the format (ev_...) and providing an example ID. The schema alone is sufficient, but the description reinforces understanding.

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?

Description clearly states the verb 'Verify' and the resource 'Evidence Bundle', specifying the cryptographic integrity checks (manifest hash, EIP-191 signature, R2 artifact hashes). It distinguishes itself from sibling tool bundle.get for quick metadata lookups without full verification.

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: to confirm a bundle has not been tampered with. Provides alternative tool (bundle.get) for quick metadata lookups. Also mentions related tools receipt.list and receipt.verify for the receipt. Includes example prompts to guide 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?

Discloses async indexing, need to poll job.status, and return of a receipt. Annotations already indicate idempotent and non-destructive, but description adds behavioral context beyond annotations, such as the prerequisite checks and return structure.

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?

Well-structured with front-loaded purpose, then step-by-step, prerequisites, returns, and examples. Slightly verbose with example prompts, but all information earns its place. 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?

Covers all necessary context: flow (async indexing), prerequisites, returns (including receipt), and examples. Given output schema and annotations, description is complete for this moderately complex tool.

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

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

Schema coverage is 100% with descriptions for each parameter. Description does not add significant semantic meaning beyond what schema provides, but it does give usage context (e.g., 'Use after collection.create'). 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 verb 'Add' and the resource 'evidence bundle to a collection', and distinguishes from siblings like collection.create (creates collection) and collection.search/ask (query). It specifies the action and its 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?

Explicitly says 'Use after collection.create' and provides prerequisites: bundle must have status 'complete', collection owned by API key. Includes instructions on polling job.status and gives example prompts, offering clear guidance on when and how 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 indicate read-only and idempotent. Description adds process details (retrieves chunks, synthesizes with citations) and mentions prerequisites, which enriches understanding beyond annotations. No contradictions.

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?

Description is well-structured with main purpose first, then usage guidance, prerequisite, output format, and examples. No redundancy; every sentence provides essential 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?

Given complexity of RAG tool, description covers purpose, usage context, prerequisites, output format, and examples. Schema covers parameters fully. Overall very complete for an 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?

Input schema has 100% coverage with descriptions and examples. Description adds value by noting default for max_chunks (8) and usage advice (increase for broad questions, decrease for precision), enhancing parameter semantics beyond 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 answers a question using RAG over a document collection, synthesizing cited answers. It explicitly distinguishes from sibling tools 'collection.search' (raw chunks) and 'url.qa' (single-document Q&A), providing high specificity.

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?

Description explicitly states when to use (need direct answer grounded in collection documents) and when not to use (use collection.search for raw chunks, url.qa for single documents). Also notes prerequisite that collection must be populated and indexed.

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 significant behavioral context beyond annotations: free (no credits), starts empty, async indexing, return shape. No contradictions with annotations (readOnlyHint=false, etc.).

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?

Well-structured: purpose, usage notes, return shape, examples. No fluff; every sentence adds 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?

Given 1 parameter, complete schema, output schema described, annotations present, description covers creation, usage, side effects, and examples. Fully adequate for agent understanding.

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 parameter 'name' with description and example. Description adds no new parameter details beyond the schema, but example prompts show usage. Schema coverage is 100%, so baseline 3.

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?

Clearly states verb 'create' and resource 'named document collection', explains purpose (cross-document semantic search and RAG). Distinguishes from siblings like collection.list and collection.search.

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 when to use ('group related evidence bundles') and describes prerequisites (start empty, need add_document). Provides example prompts for context. Lacks explicit exclusions or alternative tools but sufficient.

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 behavioral context beyond annotations: states it is free (no credits consumed), supports pagination, and returns a specific structure. Annotations already indicate read-only and idempotent, so description complements them well.

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?

Well-structured with main purpose first, followed by usage guidance, return format, and examples. Slightly lengthy but all content is relevant and earns its place.

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?

Complete for a simple list tool: covers purpose, usage context, parameters, return value, and examples. No gaps given the low complexity and full schema/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 100%, so the schema fully documents limit and offset. The description adds value by explaining pagination context and showing example output, going beyond just repeating schema details.

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?

Clearly states 'List all document collections owned by your API key' with specific verb and resource. Distinguishes from sibling tools like collection.search and collection.ask by mentioning it is used to get collection IDs. Also notes it is free and uses no credits.

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 advises using this tool before collection.search or collection.ask when needing the collection ID. Provides example prompts that illustrate common use 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 already declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. Description adds value by stating it's free, detailing the return structure (bundle_id, chunk_id, text, score, optional title), and explaining the async indexing prerequisite. No contradictions.

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?

Concise, well-structured description with clear sections: purpose, usage guidance, prerequisite, return format, and example prompts. Every sentence adds 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?

Given the tool complexity and the presence of an output schema, the description covers all necessary context: purpose, alternatives, prerequisites, return format, and examples. Sibling tools are listed for further reference.

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?

Input schema covers 100% of parameters with descriptions and examples. The description does not add parameter-level detail beyond the schema, but it provides context about when parameters are used. 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 'Semantic (vector) search across documents in a collection' and specifies it returns 'ranked text chunks with relevance scores'. It distinguishes from sibling `collection.ask` by contrasting raw chunks vs synthesized answers.

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 this tool ('when you need raw matching chunks') and when to use the alternative ('collection.ask'). Also lists prerequisite (collection must be populated and indexing complete) and notes it's free.

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 show readOnlyHint and idempotentHint true, but the description adds that it uses a quality AI model with citation-level evidence, explains max_tokens truncates input not output, and details the return format. No contradictions.

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 purpose and usage, then return format, then examples. Every sentence adds value, no filler. It is appropriately sized for 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 3 parameters and a detailed output schema included in the description, the context is complete. It explains workflow, alternatives, return format with example prompts. No gaps remain.

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 baseline is 3, but the description adds significant value: it explains where to get text (extract_text/url.extract), gives examples for claims and max_tokens, and clarifies max_tokens truncates input. This exceeds minimal compensation.

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 verifies factual claims against document text, using a quality AI model with citation-level evidence. This specific verb-resource combination distinguishes it from siblings like url.qa (open-ended questions) and collection.ask (multi-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 says to use after document.extract_text or url.extract, provides a typical workflow, and names alternatives (url.qa for open-ended, collection.ask for multi-document). This gives clear when-to-use and when-not-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?

Annotations already declare readOnlyHint and idempotentHint. Description adds 'Uses a quality AI model with retry logic' and details the return format including confidence levels and citations. 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?

Description is a single paragraph but well-structured: purpose, usage, schema format, return format, examples. Every sentence adds value. Could be slightly more concise, 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?

Given the tool's complexity (custom schema extraction) and the presence of an output schema, the description covers all critical aspects: purpose, usage context, parameter example, return structure, and behavioral traits. No gaps.

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

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

Schema coverage is 100%, providing the baseline. Description goes beyond by offering concrete examples for the 'schema' parameter format and clarifying 'max_tokens' truncation behavior. Adds meaningful context without redundancy.

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 'Extract typed fields from document text using a caller-defined schema.' It specifies the verb (extract), resource (structured data), and distinguishes from siblings like 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?

Explicitly says 'Use when you need specific data points...' and provides alternatives: 'For invoices... document.parse_invoice...' and 'For general summarization, use document.summarize.' This gives clear when-to-use and when-not-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 annotations (readOnlyHint=true, idempotentHint=true) declare the tool as safe and idempotent. The description adds value by disclosing the return format '{ pages: number, text: string }' with Markdown-formatted text, the base64 encoding requirement, and a maximum document size of ~15 MB. 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 concise, with clear front-loading of purpose, followed by usage guidelines, return format, and example prompts. Every sentence serves a purpose 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?

Given the tool's low complexity (2 parameters, simple input/output), the description fully covers functionality, input constraints (base64, size, MIME types), output format, and appropriate use cases. It even includes example prompts for common user intents.

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 detailed descriptions for both parameters (mime_type enum with examples, document_base64 with example and size limit). The description does not add significant new meaning beyond the schema; it mentions base64 encoding generally but doesn't elaborate further. 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 'Extract tables and forms as Markdown from a PDF or image (base64-encoded).' It specifies the verb (Extract), the resource (tables and forms from PDF/image), and the output format (Markdown). It also distinguishes itself from the sibling tool document.extract_text, which handles plain prose.

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 the document contains structured tabular data such as financial statements, data sheets, or forms.' It also provides a clear alternative: 'For plain prose documents, use document.extract_text 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 and idempotentHint as true, so description adds value with size limit (~15 MB) and return format ({pages, text}). No contradictions.

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

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

Three short paragraphs: purpose, usage guidelines, return value and examples. Front-loaded with core action, every sentence adds value, no 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?

Given 100% schema coverage, complete annotations, output schema, and sibling tools, the description sufficiently covers all aspects: input constraints, use cases, alternatives, and output format.

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 parameters have descriptions. The description adds context with a realistic base64 example and supported mime types, going 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 'Extract plain text from a PDF or image (base64-encoded)', specifying verb, resource, and method. It distinguishes itself from sibling tool url.extract by noting the different input requirements.

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 raw text for downstream AI analysis' and identifies the alternative for public URLs ('use url.extract instead'). Provides example prompts for typical use 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 already declare readOnlyHint and idempotentHint, indicating safe read-only behavior. The description adds context about model quality and the return structure, which is useful but not required. No contradictions.

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 first sentence, usage guidance, return format, and examples. It is moderately sized; every sentence adds value, though the return schema could be slightly shortened.

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 annotations and output schema documentation (return block), the description is fully complete: it covers purpose, usage, return structure, and examples. No gaps remain for an AI agent to select and use this 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 has 100% description coverage for both parameters (mime_type and document_base64). The description does not add new parameter-level details beyond what the schema provides, so 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 the tool parses invoices/receipts into structured fields, using a quality AI model. It distinguishes itself from the sibling tool document.extract_text by specifying use for financial documents versus general text.

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 (extract line items, totals, merchant info) and when not to (use document.extract_text for general text). It provides example prompts that illustrate typical use 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 declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds significant behavioral context: explains the structure of the returned object (summary, key_points, cited versions, truncated flag, strategy), mentions truncation behavior for input length, and outlines the typical workflow. This goes beyond 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 appropriately sized. It includes a purpose statement, usage guidelines, workflow hint, output format specification, and example prompts. Every sentence serves a clear purpose, and the information is front-loaded.

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 (summarization with structured output), the description is complete. It covers input, output format, strategy types, truncation, and usage context. The output schema is embedded in the description, and workflow dependencies are clarified.

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 enriches both parameters: 'text' is explained with source (other tools) and an example; 'max_tokens' explains default and effect (truncates input, not output) with an example. This adds practical meaning 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 explicitly states 'Summarize document text into a prose summary and key points with citations.' It differentiates from siblings by specifying alternatives: 'For single-sentence Q&A, use url.qa instead. For extracting specific fields, use document.extract_structured.' The purpose is clear and specific.

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 guidance on when to use the tool ('Use after document.extract_text or url.extract') and when not to, with direct references to sibling tools. It also includes example prompts that illustrate typical 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. The description adds useful context: 'Free — no credits consumed' and explains what happens at different statuses (complete/failed includes bundle_id or result_json). No contradictions.

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: purpose, usage, return format, and example prompts. Every sentence adds value without 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 the output schema is provided within the description, it covers all return fields. It also explains job creation sources and how to use the tool in a polling loop. For a simple polling tool, 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 coverage is 100% but the description adds context: 'Job ID (job_...) returned by async extract or collection.add_document. Example: job_550e8400-...' which clarifies the parameter's origin and format 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 'Poll the status of an async job (extract, indexing, batch)' with a specific verb and resource. It distinguishes from sibling tools like collection.add_document or url.extract by focusing on status polling.

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 says when to use: 'Use after collection.add_document or async extract to check when processing completes.' It also provides guidance on polling loop: 'Poll this endpoint in a loop until status is complete or failed.' It does not explicitly state when not to use, 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 already indicate readOnlyHint and idempotentHint. The description adds that the operation is free and credits are not consumed, enhancing transparency 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?

Information is well-structured and front-loaded: purpose, usage, return format, examples. Some redundancy in examples and return format could be trimmed, but overall efficient communication.

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 purpose, usage context, return format, and example prompts. With an output schema present, return values are adequately documented. Minor gaps like error handling or edge cases are not critical for this simple read tool.

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

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

Schema descriptions cover all three parameters with examples and defaults. The description does not add significant additional semantics beyond restating the bundle_id context. Schema coverage is 100%, 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 verb 'list' and the resource 'signed action receipts' scoped to an evidence bundle owned by the API key. It distinguishes from the sibling tool receipt.verify, making 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?

Explicitly states when to use: after bundle.get, bundle.verify, bundle.notarize, or collection.add_document. Also provides an alternative path: using receipt_id for subsequent verification via receipt.verify.

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?

Description adds beyond annotations: free, no credits consumed, explains what the verification proves (authenticity + manifest match). Annotations already declare readOnly and idempotent, no contradiction.

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?

Description is well-organized with sections, example, and output schema. Slightly verbose with example prompts but 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?

Covers purpose, parameters, return values (via output schema), use cases, and examples. No gaps given tool 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?

Single parameter receipt_id. Schema has description, but description adds origin (from other tools) and example. Adds value beyond schema, though schema coverage is 100%.

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?

Description clearly states the tool verifies a signed action receipt, distinguishes it from siblings like receipt.list and bundle.get, and provides explicit purpose via verbs 'independently verify' and example prompts.

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?

Context is clear: use for third-party audit. Example prompts guide appropriate usage. No explicit when-not-to-use, but siblings imply 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?

Description adds significant behavioral context beyond annotations: 'Lean mode — no evidence bundle stored, no bundle_id returned' and mentions returning final_url after redirects. Annotations already indicate readOnlyHint=true and openWorldHint=true, but description enriches understanding.

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?

Description is concise: first sentence states core function, then lists alternatives, return structure, and example prompts. Every sentence is purposeful and well-organized.

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 output schema present, description adequately covers input, output format, and usage. The tool is simple (1 parameter) and description is thorough for effective agent invocation.

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 description need not add much. It provides example prompts helping agent format the url parameter correctly, adding value beyond 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?

Description clearly states verb 'Fetch', resource 'public HTTPS URL', and output 'extracted text and page metadata'. It distinguishes from siblings like url.summarize, url.qa, url.translate, and document.extract_text.

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 when to use this tool ('raw text extraction') and when not (instead use url.summarize for summaries, url.qa for Q&A, url.translate for translation, document.extract_text for base64 file uploads). Provides clear context.

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 provide readOnlyHint=true and openWorldHint=true, indicating safe read operation. The description adds value by disclosing 'Lean mode — no bundle stored', and detailing return fields including confidence and truncation. 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 concise, front-loaded with the main purpose, and structured with return fields and example prompts. Only minor redundancy (e.g., 'Example:' wording), 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?

Given the tool has an output schema (implied) and 3 parameters, the description lists all key return fields (url, answer, answer_cited, confidence, truncated) and provides example prompts. It is complete for the 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?

Schema coverage is 100%, with all three parameters described in the input schema. The description does not add new parameter semantics beyond what the schema already provides, 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 fetches a public HTTPS URL and answers a specific question, using a precise verb and resource. It distinguishes itself from siblings url.summarize and collection.ask, 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?

Explicitly states when to use: 'when you have a precise question about a web page'. Also provides clear alternatives: 'For a broad summary, use url.summarize. For multi-document Q&A, use collection.ask instead.' This gives both inclusion and exclusion criteria.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds that the tool is 'Lean mode — no bundle stored' (no persistence) and that it truncates fetched page content based on max_tokens. This provides useful behavioral context beyond 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?

Description is 4 sentences plus a return type list. Core action is front-loaded. Example prompts are helpful but could be condensed. No extraneous information.

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

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

With an output schema present, the description provides sufficient context: usage, alternatives, limitations (truncation), and return structure. Covers all necessary aspects.

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%. The description adds meaning by explaining max_tokens: 'Input length cap (1 token ≈ 4 chars). Truncates fetched page content, not the output summary.' Also provides example prompts showing typical usage.

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 fetches a public HTTPS URL and returns a prose summary with key points. It distinguishes from siblings by mentioning 'Lean mode — no bundle stored' and contrasts with url.extract (raw text) and url.qa (specific questions).

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 a condensed understanding of a web page.' Provides clear alternatives: 'For raw text, use url.extract. For asking a specific question about a page, use url.qa.'

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?

Discloses 'lean mode — no bundle stored' beyond annotations. Mentions truncation behavior and return fields. No contradiction with annotations (readOnlyHint, openWorldHint).

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?

Concise: first sentence states purpose, then usage guideline, return format, and examples. No redundant information. Well-structured with bullet for return and examples.

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 complexity (fetch, translate, language codes, truncation), description covers return fields and truncation. Distinguishes from siblings effectively. Annotations present. Complete for this tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value through example prompts demonstrating parameter usage and output structure, though schema already explains parameters fully.

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?

Description clearly states the action ('fetch and translate'), the resource ('public HTTPS URL'), and the output. It distinguishes itself from sibling url.extract by specifying 'no bundle stored' and contrasting with 'raw untranslated text'.

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: 'when you need to understand web content in a different language.' Provides a clear alternative: 'for extracting raw untranslated text, use url.extract instead.'

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