api

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

The description discloses write behavior (adds and triggers indexing), async processing, and the need to poll for completion. This goes beyond the annotations (which only indicate non-read-only and non-destructive) by explaining the exact workflow 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?

The description is compact yet complete, with five sentences each serving a distinct purpose: purpose, prerequisite, async behavior, and return structure. No redundant or superfluous 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 the tool's complexity (async workflow, prerequisites, 3 parameters, no output schema), the description covers all necessary aspects: what it does, required conditions, how to handle the async result, and what the response contains. It fully equips an agent to 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 description coverage is 100%, so the schema already documents parameters. The description adds value by linking bundle_id to a status check and clarifying that collection_id must be owned by the API key. It also mentions the optional title parameter, but overall the description supplements rather than replaces 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?

The description clearly states the verb ('add'), the resource ('evidence bundle to a collection'), and the added behavior ('trigger async vector indexing'). It distinguishes from siblings like search_collection and ask_collection which are query tools, leaving no ambiguity about the tool's primary function.

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 prerequisites are given: bundle must have status 'complete' and collection must be owned by the API key. The async nature and polling instructions are provided. While it does not explicitly list when not to use, the context is strong enough for an agent to infer 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 indicate readOnlyHint=true; description aligns by describing a read-only retrieval and synthesis process. Adds context about RAG mechanics, prerequisite, and output structure 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?

Each sentence serves a distinct purpose: purpose, sibling differentiation, prerequisite, output format. No redundancy, front-loaded with core action.

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 RAG tool with no output schema, the description provides complete context: purpose, usage, prerequisite, and explicit return structure covering answer, sources, and retrieval chunks.

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% description coverage, so baseline is 3. The description adds value by explaining usage of max_chunks ('increase for broad questions, decrease for precision'), raising it to 4.

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 it answers questions using RAG over document collections, with specific verb 'answer' and resource 'collection'. It distinguishes from the sibling search_collection by stating when to use each.

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

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

It provides clear when-to-use (direct answer with citations) and when-not-to (raw chunks via search_collection). Also includes a prerequisite about collection population, aiding correct invocation.

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 AI quality note and output format but 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 two-paragraph structure, front-loaded purpose, no fluff.

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: covers purpose, workflow, parameters, and return format despite no 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 covers all params. Description adds example for claims array and mentions max_tokens cap, slightly enhancing clarity.

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?

Clear verb+resource: 'Verify a list of factual claims against document text.' Distinguishes from siblings like extract_text and ask_collection.

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 workflow: call extract_text or extract_url first. Lacks when-not-to-use but context is strong.

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 annotations (destructiveHint=false), describes async indexing, initial emptiness, and return format. 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?

Two short paragraphs, front-loaded with purpose. Every sentence adds value, no filler.

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

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

For a simple creation tool with one parameter, the description covers workflow (empty then add), async behavior, return structure, and cost. Fully sufficient for correct 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?

Only one parameter 'name' with schema coverage 100%. Description adds context with a concrete example ('e.g. Q4 Contracts or Due Diligence Docs'), exceeding 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?

Clearly states the verb 'create', resource 'named document collection', and purpose 'for cross-document search and Q&A'. Distinct from sibling tools like 'add_document_to_collection' and 'search_collection'.

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

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

Provides explicit when-to-use context: 'Free — no credits consumed' and notes that collections start empty, requiring subsequent adding of documents and async indexing before search/ask. Lists alternative tools for later steps.

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 annotations (readOnlyHint, idempotentHint), the description adds that it uses a quality AI model with retry logic, truncates input via max_tokens, and returns confidence and citations. This provides valuable behavioral context.

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

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

The description is concise, with each sentence serving a purpose. It could be slightly more streamlined, but it is not 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?

Despite lacking an output schema, the description fully explains the return structure. It covers inputs, behavior, and schema format. Missing error handling details, but overall 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?

With 100% schema coverage, the description still adds meaning: it explains the schema format with an example, suggests text sources (extract_text, extract_url), and clarifies max_tokens defaults and 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 the tool extracts typed fields from document text using a caller-defined schema. The verb 'extract' and resource 'typed fields' are specific, and it distinguishes from siblings like extract_text (raw text) and parse_invoice (invoice-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 indicates usage when you have document text and need custom structured data, and it provides a schema format example. However, it does not explicitly state when not to use it or compare with alternatives like parse_invoice.

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 value by disclosing the return format ({ pages, text }) and input constraints (base64-encoded, max ~15 MB), which go beyond the structured fields. 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 concise: two sentences plus a return format note. It is front-loaded with the main action and contains no redundant 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?

The tool has 2 simple parameters, clear annotations, and no output schema. The description covers input, output, use case, and alternatives. Although it doesn't mention error cases, it is complete enough 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?

With 100% schema description coverage, the schema already documents both parameters well. The description does not add new meaning beyond the schema, so 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 clearly states the verb 'Extract', the resource 'tables and forms as Markdown from a PDF or image (base64-encoded)', and distinguishes itself from 'extract_text' by specifying when to use it for structured tabular data versus 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?

The description explicitly says 'Use when the document contains structured tabular data. For plain prose, use extract_text instead.' This provides clear context for when to use the tool and an alternative, though it could mention other siblings like 'extract_structured' for more structured output.

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 idempotentHint=true. The description adds the return format but does not disclose additional behavioral traits beyond annotations. It does not contradict annotations, so a baseline score is appropriate.

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 two sentences: first states purpose and input, second provides alternative and return format. No redundant information, well-structured and 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 full schema coverage and clear annotations, the description is almost complete. It includes return type and alternative usage. Missing mention of error handling or edge cases like empty documents, but sufficient for most scenarios.

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 parameters are fully documented in the schema. The description repeats the base64 parameter info but does not add new meaning 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 tool extracts plain text from base64-encoded PDFs or images, specifying the verb and resource. It also distinguishes from the sibling tool extract_url for URL-based documents.

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 indicates when to use this tool (base64 input) and when to use extract_url instead (public HTTPS URL). However, does not address other sibling extraction tools like extract_structured or extract_tables, but their purposes are distinct.

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, indicating no side effects. The description adds important context that no evidence bundle is stored and no bundle_id is returned, which is valuable beyond annotations. However, it could mention error handling or redirect behavior more explicitly.

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 extremely concise: two sentences plus a list of return fields. Every sentence adds value, and the structure is front-loaded with the core purpose and key differentiator (lean mode).

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 one parameter and clear annotations, the description is fairly complete: it explains the purpose, usage guidance, and return format. The return fields are listed even though there is no output schema. Minor gap: could mention what happens if the URL is invalid or non-HTTPS, but not critical.

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?

There is only one parameter (url) with full schema coverage (100%) including format and description. The tool description does not add additional explanation beyond what the schema provides, so 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 clearly states the tool fetches a public HTTPS URL and returns extracted text and page metadata. It specifies 'lean mode' meaning no evidence bundle is stored, and distinguishes itself from sibling tools like summarize_url, qa_url, and translate_url.

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 provides when to use this tool ('Use for raw text') and when to use alternatives ('Use summarize_url for summaries, qa_url for Q&A, translate_url for translation'). This is excellent guidance for an agent to select the correct tool.

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

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

Annotations already provide readOnlyHint and idempotentHint, indicating safe, repeatable operation. Description adds that the tool is free and returns specific fields, and implies it only accesses bundles owned by the API key. 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 sentences with a code block for return fields. Front-loaded with purpose and usage. Slightly verbose with code block but effective.

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?

Low complexity with one parameter and no output schema. Description covers purpose, usage, and return fields with a JSON example. Missing error handling details but sufficient for its simplicity.

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 schema coverage 100% and clear description. The tool description does not add extra details 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?

Specifies verb 'retrieve', resource 'metadata for evidence bundle', and scope 'owned by your API key'. Distinguishes from sibling verify_bundle by mentioning deep integrity checks vs quick lookups.

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 get_bundle vs verify_bundle: 'Use verify_bundle for deep cryptographic integrity checks. Use get_bundle for quick status/metadata lookups.' Also notes it is 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?

Discloses cost (free), polling termination condition, return fields including progress_pct and error handling. Adds context beyond annotations (readOnlyHint, idempotentHint) about the behavior and returned data 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?

Description is compact, with clear sentences. First sentence states purpose, then cost, creation, polling advice, completion info, and a structured return format. 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?

Despite no output schema, description provides a detailed return object with all fields and statuses. Covers purpose, usage, return types, and error handling completely for a one-parameter tool.

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

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

Schema coverage is 100% (baseline 3). Description adds context by explaining where job_id comes from (async extract or add_document_to_collection), which provides additional clarity beyond the schema 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?

Description clearly states 'Poll the status of an async job' with specific verb 'poll' and resource 'async job status'. It lists job types (extract, indexing, batch) and differentiates from sibling tools which do not include a polling function.

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?

Explains when to poll (until 'complete' or 'failed'), describes when jobs are created (via POST /v1/extract webhook or add_document_to_collection), and mentions what completed jobs include. Does not explicitly state when not to use, but no alternative 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 already declare readOnlyHint and idempotentHint as true. The description adds behavioral context: it's free, consumes no credits, and shows the return structure including plan_id, billing_period, credits_used, credits_limit, credits_remaining, and status. 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?

Three sentences: first declares purpose, second provides usage guidance, third shows return format. No filler; every sentence adds value. Highly 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 no parameters and clear annotations, the description covers purpose, usage context, and return structure. Without an output schema, providing the return fields is essential and 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?

No parameters. Schema coverage is 100% (empty schema). The description confirms no input needed, which adds meaning beyond the schema. Baseline 4 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?

Clearly states it gets current credit balance and plan details for the API key. The verb 'get' combined with 'quota' and the specific resource makes the purpose unambiguous. Since siblings are unrelated (e.g., document, collection tools), it effectively distinguishes itself.

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 before running expensive operations to check available credits.' This provides clear when-to-use guidance. While it doesn't mention when not to use or alternatives, the context is sufficient for a simple read-only tool.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds value by specifying the cost (free) and return format, which is 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?

Two sentences: one for purpose, one for return format. No superfluous words, highly efficient.

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

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

For a simple list tool with good annotations and schema, the description covers purpose, scope, cost, and return format. It could mention pagination behavior, but schema covers limit/offset.

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 for both parameters (limit and offset), so the description does not need to add parameter details. It correctly does not repeat schema information.

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 'document collections' with a specific scope 'owned by your API key,' distinguishing it from sibling tools like create_collection or search_collection.

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 notes 'Free — no credits consumed' and 'owned by your API key,' providing clear context on when to use. However, it does not explicitly exclude alternatives or state 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 idempotentHint=true and destructiveHint=false. Description adds valuable context: gas costs, permanence of the record even if bundle is purged, and the attestation return structure. 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?

Very concise and well-structured: purpose first, then prerequisite, cost/permanence, return format. Every sentence is informative 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?

Description covers all necessary aspects for a one-parameter tool without output schema: purpose, prerequisite, side effects (cost, permanence), idempotency, and return fields. Thorough and 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?

Single parameter bundle_id has full schema coverage (100%). Description repeats schema info and adds prerequisite context, but does not significantly expand 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?

Description clearly states the tool notarizes an evidence bundle on-chain by writing its manifest SHA-256 to the blockchain, forming a permanent tamper-evident record. It uses specific verbs and resources, differentiating from siblings like verify_bundle.

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?

Includes explicit prerequisite (bundle status must be complete) and instructs to check with get_bundle. Notes idempotency and gas costs. Lacks explicit alternatives but provides strong context for appropriate 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 readOnlyHint=true and idempotentHint=true, which the description aligns with ('Parse' implies read-only). The description adds minimal behavioral context beyond 'uses a quality AI model,' so it doesn't significantly enhance transparency 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 description is very concise with two sentences plus a structured return format. No wasted words; the purpose 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 no output schema, the description provides a complete return structure, which is crucial for the agent to understand the tool's output. Parameters are fully covered by the schema, and the purpose is clear.

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. The description adds value by detailing the return structure (invoice and cited fields), compensating for the lack of an output schema. This helps agents understand what parameters map to in the output.

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 'Parse a receipt or invoice document into structured fields,' which is a specific verb+resource combination. It distinguishes itself from sibling tools like extract_text or extract_structured by being tailored for invoices/receipts.

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?

No explicit guidance on when to use this tool versus alternatives. The description only mentions 'Uses a quality AI model for accuracy,' but does not explain when not to use it or name alternative tools for similar tasks.

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 readOnly and openWorld hints. Description adds that it fetches a public HTTPS URL, uses lean mode with no bundle storage, and returns truncated content if needed. 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 sentences: purpose, lean mode + sibling hint, return format. Every sentence adds value, concise and 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 schema details and annotations, description covers the tool's function and return structure despite lacking output schema. Could mention other sibling tools for completeness, but not essential.

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. Description does not add extra meaning beyond what schema provides, so baseline score 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?

Description clearly states the tool fetches a public HTTPS URL and answers a specific question. It distinguishes itself from ask_collection for multi-document Q&A, and mentions 'lean mode' with no bundle storage.

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 to use for single URL Q&A and to use ask_collection for multi-document. Does not mention other alternatives like summarize_url or extract_url, but provides clear guidance for the primary 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 already indicate readOnlyHint and idempotentHint; description adds that operation is free (no credits consumed) and explains async indexing prerequisite. 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?

Two-paragraph structure is front-loaded with purpose and result format; second paragraph covers prerequisite and sibling comparison. 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?

With 3 parameters, high schema coverage, and annotations, the description provides purpose, usage guidance, prerequisite, sibling differentiation, and return format. Complete for 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 parameters are already described. Description adds value by specifying return format including score range (0-1) and fields, but does not enhance parameter understanding 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 semantic (vector) search across documents in a collection, returning ranked text chunks. Distinguishes from sibling ask_collection by specifying raw vs synthesized results. Specific verb+resource.

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 prerequisite (collection must be populated and indexed) and provides clear guidance on when to use this tool vs ask_collection. No explicit exclusions but 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=true and idempotentHint=true. Description adds behavioral details: the return object structure (summary, key_points, citation variants, truncated, strategy) and that max_tokens truncates input, not output. 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 generally concise, with two sentences stating purpose and workflow. However, the included JSON block for return format is somewhat lengthy. Front-loading of purpose and guidelines is good. Could be slightly more succinct, but still effective.

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 only 2 parameters (with 100% schema coverage) and no output schema, the description fully covers the return format, typical usage, and parameter details. It leaves no significant gaps for an AI agent to understand invocation and expected results.

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

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

Schema coverage is 100%, but the description adds meaning: for 'text' it says 'Obtain via extract_text or extract_url', tying parameter to workflow. For 'max_tokens' it clarifies input truncation and provides token-to-character ratio. Both enhance understanding beyond schema alone.

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 verb ('Summarize') with specific scope ('document text into a prose summary and key points'). It distinguishes from siblings like 'summarize_url' by specifying that the input must be text (obtained via extract_text/extract_url), not a URL.

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 provides a typical workflow: call extract_text or extract_url first, then pass the text here. This tells when to use this tool and implies that for direct URL input, 'summarize_url' would be used. Also explains max_tokens param behavior and default.

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 openWorldHint, but the description adds behavioral context: it fetches a public URL (network side effect) and does not store a bundle (no persistence). Return structure is also partially specified. 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?

Two sentences with zero waste. Key information is front-loaded (verb, resource, output type). The return format is listed succinctly.

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 explains the output structure despite no output schema, and includes the lean mode detail. For a simple tool with good schema and annotations, it covers necessary context, though it could mention potential rate limits or URL format requirements.

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 clear descriptions for both parameters (url, max_tokens). The description does not add new parameter semantics beyond the schema; it only hints at usage context (lean mode) which does not pertain to parameters directly.

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 differentiates from siblings like extract_url (text extraction) and qa_url (Q&A) by specifying the summarization output and 'lean mode — no bundle stored'.

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 mentions 'lean mode — no bundle stored' as a differentiator but does not explicitly guide the agent on when to use this tool versus alternatives like summarize_document or extract_url. No when-not-to-use or prerequisite information is provided.

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, and the description aligns by stating no bundle is stored. The description adds value by mentioning truncation via max_tokens and the return format, providing 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 description is extremely concise, with two sentences and a return spec. No unnecessary words, front-loaded with the action, and 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 (3 params, no output schema), the description covers the main behavior: fetching, translating, and returning results with truncation. However, it could briefly mention limitations (e.g., only public HTTPS, language code support) for full completeness.

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 parameters are already documented. The description adds extra context for max_tokens (1 token ≈ 4 chars) and clarifies the return structure ({ url, translated_text, target_lang, truncated }), 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 the tool fetches a public HTTPS URL and returns translated content, with a specific verb ('fetch', 'translate') and resource ('URL'). It distinguishes from siblings like extract_url, qa_url, and summarize_url by focusing on translation and 'Lean mode — no bundle stored'.

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?

No explicit guidance on when to use this tool versus alternatives. The description mentions 'Lean mode — no bundle stored,' implying it's for cases where no persistence is needed, but does not specify when not to use it or name sibling tools like qa_url or extract_url for comparison.

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 and idempotentHint. The description adds that the tool is free (no credits consumed) and details the return structure including checks and tampered array. This provides 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?

The description is concise: a single paragraph that introduces the purpose and then lists the return fields in JSON. It is front-loaded with the main action. Every sentence adds value, though the return type could potentially be in an output schema.

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 low complexity (one parameter, clear schema, and annotations), the description covers the essential aspects: purpose, input, output format, cost, and ownership constraint. It could mention error cases or rate limits, but but it is sufficiently complete for a simple verification 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 single parameter bundle_id is described in the schema as the bundle ID from extract or notarize. The description adds that the bundle must be 'owned by your API key', which is extra context beyond the schema. With 100% schema coverage, this is a meaningful addition.

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 verifies cryptographic integrity of an evidence bundle and lists specific checks (manifest hash, signature, artifact hashes). It distinguishes from siblings like get_bundle and notarize_bundle by its action (verify) and details, though it does not explicitly differentiate.

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 implies use after extracting or notarizing a bundle (bundle_id from those) and notes it is free. However, it does not explicitly state when to use this tool over alternatives like get_bundle or when not to use it.

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