DocImprint

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

Annotations show readOnlyHint=false and destructiveHint=false, indicating mutation but not destruction. The description adds significant context: indexing is async, returns a job_id for polling, and the document becomes searchable only after completion. 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 (4 sentences) with clear sections: purpose, prerequisite, async behavior, return value. No unnecessary words; 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?

Despite no output schema, the description fully specifies the return object and explains the async indexing process. It covers prerequisites and expected behavior, though error handling is omitted.

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 each parameter. The description reinforces prerequisites (bundle must be complete, collection from create_collection) but adds little new meaning, 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 uses specific verbs ('Add... and trigger...') and identifies the resource (evidence bundle to collection). It clearly distinguishes from sibling tools like search_collection and ask_collection by mentioning the indexing outcome.

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 prerequisites (bundle must be 'complete', collection owned by API key) and notes that indexing is async, guiding the user to poll get_job_status. It does not explicitly state when not to use this tool, 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?

Describes the RAG process (retrieve chunks then synthesize answer) and discloses the return structure. Annotations already declare readOnlyHint=true, and the description adds rich behavioral detail without 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?

Very concise: 3 sentences plus a return type block. Well-structured with purpose, usage, prerequisite, and output. 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 the RAG complexity, 3 parameters, and no output schema, the description fully covers the tool's behavior, prerequisites, and return format. Nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description does not add parameter-specific semantic beyond what the schema provides, warranting a 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 'Answer a question using RAG over a document collection' with specific verb and resource. Explicitly distinguishes from sibling search_collection by contrasting use cases.

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

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

Explicitly tells when to use ('direct answer with source attribution') and when not ('use search_collection for raw chunks'). Also includes a prerequisite about collection population.

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

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

Annotations already mark the tool as readOnly and idempotent. The description adds valuable behavioral details: uses 'quality AI model', truncation behavior ('Truncates input, not output'), and the exact return format including fields like 'truncated' boolean.

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 (3 sentences + JSON snippet) with no filler. It front-loads the purpose, then workflow, then return format. 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 has 3 parameters with full schema coverage and no output schema, the description provides the output structure and truncation behavior, making it complete for the agent to understand inputs, outputs, and side effects.

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% for all 3 parameters, so the baseline is 3. The description adds marginal value by including an example in the claims parameter doc and clarifying the return format, but does not significantly enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Verify a list of factual claims against document text.' It uses a specific verb ('verify') and resource ('claims'), and the purpose is distinct from all sibling tools (no other claim verification tool).

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 workflow guidance is provided: 'Typical workflow: call extract_text or extract_url first to get the text, then pass it here.' This tells the agent when to use this tool and what prerequisites are needed.

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

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

Beyond the annotation (destructiveHint: false), the description discloses that creation is free and consumes no credits, collections start empty, indexing is asynchronous, and the return format includes collection_id and name. 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 the core purpose stated first, followed by essential notes in a structured format. Every sentence adds value, 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?

For a simple creation tool with one parameter and no output schema, the description covers all necessary aspects: what it does, usage guidelines, behavioral notes, and return format. 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?

The input schema already provides a clear description for the sole parameter 'name'. The description adds example values ('Q4 Contracts') and reinforces the usage context, adding value beyond the schema. With 100% schema coverage, baseline is 3; the extra context justifies a 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 clearly states the verb 'Create' and the resource 'named document collection'. It specifies the purpose: 'for cross-document search and Q&A'. It distinguishes from sibling tools like add_document_to_collection and search_collection by setting up the creation as the first step.

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

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

Provides explicit usage flow: collections are empty after creation, use add_document_to_collection to add evidence bundles, and after async indexing, use search_collection or ask_collection. This tells the agent when to use this tool and what to do next, differentiating from siblings.

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, signaling safe, non-mutating behavior. The description adds valuable behavioral context: uses a quality AI model with retry logic, truncates input not output, and describes the return format with citations and confidence levels. 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 and well-structured. The first sentence immediately states the core purpose. The subsequent sentences provide schema format and return format without any fluff. Every sentence adds value and is appropriately 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 moderate complexity and the fact that there is no output schema, the description provides full context: it covers input source, schema definition, retry logic, model quality, and detailed return format. Annotations handle safety. The description is complete enough for an agent to invoke 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%, but the description adds significant meaning beyond the schema: it explains the schema format with a concrete example, notes the default max_tokens and truncation behavior, and explains the output structure including data_cited with citations. This fully compensates for any lack of output 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 extracts typed fields from document text using a caller-defined schema. It uses a specific verb 'extract', a clear resource 'typed fields', and the distinct approach of using a user-defined schema. This distinguishes it from siblings like extract_text (raw text) and parse_invoice (specific pre-defined schema).

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

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

The description implies usage context: 'Obtain via extract_text or extract_url' suggests a prerequisite. It gives examples of schema format, which guides the caller. However, it does not explicitly state when not to use this tool or compare to other extraction tools 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. Description adds return format details, which provides useful behavioral context without 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?

Two sentences plus a returns line. Front-loaded with purpose, condition, and alternative. 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?

Complete description given simple 2-param schema, annotations, and no output schema. Covers purpose, usage, return format, and alternative.

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. The description does not add significant new 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?

Clearly states it extracts tables and forms as Markdown from PDF or image. Distinguishes from sibling extract_text for 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 (structured tabular data) and when not (plain prose, suggesting 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 true, and the description adds the return value structure ({pages, text}) and input size limit (in schema). No contradictions and adds 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?

Two sentences plus a return type line, no superfluous words. Front-loaded with action and resource.

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 2-parameter tool with no output schema, the description covers what it does, when to use an alternative, and the return format. Sufficient for correct 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 covers 100% of parameters with descriptions, and the tool description adds no additional meaning beyond what is in the schema. Baseline 3 is appropriate.

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

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

Description explicitly states it extracts plain text from PDF or image (base64-encoded), uses a specific verb and resource, and distinguishes from sibling extract_url by specifying when to use that alternative.

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?

Clearly advises to use extract_url when document is at public HTTPS URL, providing a direct alternative. However, it does not mention other siblings like extract_structured or extract_tables for other 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 openWorldHint. Description adds 'Lean mode — no evidence bundle stored, no bundle_id returned' and details the return fields, providing useful behavioral context beyond the annotations.

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

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

Two sentences efficiently convey purpose, usage, and output. No wasted words; front-loaded with key information.

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

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

Despite low complexity, the description covers the tool's behavior, usage context, parameter constraints, and return format. No gaps remain for effective selection and 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?

The single parameter 'url' has full schema coverage. Description adds 'public HTTPS' and lists the return fields, enhancing understanding of the parameter's constraints and the tool's 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?

Description clearly states 'Fetch a public HTTPS URL and return extracted text and page metadata.' It also explicitly contrasts with siblings like summarize_url, qa_url, and translate_url, making the tool's distinct purpose unmistakable.

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 guidance: 'Use for raw text. Use summarize_url for summaries, qa_url for Q&A, translate_url for translation.' This directly tells the agent when to use this tool versus alternatives.

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

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

Annotations declare readOnlyHint and idempotentHint. Description adds that it's free, no credits consumed, and lists return fields, supplementing 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?

Concise overall; key info front-loaded. JSON example of return fields is slightly verbose but helpful given no 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 simplicity (1 param, no nested objects, no output schema but returns list), description covers purpose, usage, constraints (ownership, cost), and return structure fully.

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 100% with one parameter. Description adds that bundle_id comes from 'extract or notarize_bundle', providing origin context beyond 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?

Clearly states verb 'retrieve', resource 'evidence bundle', and scope 'owned by your API key'. Contrasts with verify_bundle for deep checks, distinguishing purpose.

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

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

Explicitly advises using verify_bundle for integrity checks and get_bundle for quick lookups. Also notes it's free with no credits consumed, providing cost 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?

The description adds behavioral context beyond the annotations: it states 'Free — no credits consumed' (additional cost info) and details the asynchronous polling behavior. The annotations already indicate readOnlyHint and idempotentHint, and the description complements them without 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?

The description is concise and well-structured: two short paragraphs, first sentence stating purpose, followed by context and return format. 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?

Despite no output schema, the description provides a complete and detailed return object in natural language, covering all fields and states. Parameter details are sufficient for an agent to use 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% for the single parameter job_id. The description elaborates: 'Job ID (job_...) returned by async extract or add_document_to_collection', adding context about the expected format and origin beyond the schema's basic 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 the tool's purpose: 'Poll the status of an async job (extract, indexing, batch)'. It specifies the verb (poll), the resource (job status), and the scope (three job types), distinguishing it from any sibling tools.

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

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

The description explains when to use the tool: 'Poll until status is complete or failed' and mentions the context of job creation ('when you POST /v1/extract with a webhook, or when add_document_to_collection triggers async indexing'). It does not explicitly list alternatives but given there are no other polling tools, it 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?

Adds that no credits are consumed, which is not in annotations. Annotations already declare readOnly and idempotent, so description complements 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?

Five focused sentences with a JSON example. Every sentence adds value, no waste. Front-loaded with purpose.

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

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

Without output schema, description fully explains return values and usage. Completely adequate for a zero-parameter, 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 exist; schema coverage is 100%. Description adds value by detailing return structure, which is beyond schema requirements.

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 'Get current credit balance and plan details for your API key' with specific verb and resource. It distinguishes from siblings like check_claims by its unique focus on quota.

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 use before expensive operations and notes it's free. Lacks explicit alternatives but provides clear context for 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 already declare readOnlyHint=true and idempotentHint=true. The description adds value by stating the tool is free, consumes no credits, and shows the return format, which informs the agent about cost and output 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 extremely concise, with two sentences and a clear return format. 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?

For a list tool with two optional parameters and no output schema, the description covers the core functionality, return format, and cost. It is mostly complete, though it could mention default ordering or that it returns all collections by default.

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 parameters are already documented with limit/offset details. The description does not add further parameter insight beyond the schema, meeting the baseline expectation.

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

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

The description clearly states 'List all document collections owned by your API key', using a specific verb and resource. It distinguishes from sibling tools like create_collection and search_collection by focusing on listing.

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 'Free — no credits consumed', implying a cost benefit, but does not provide explicit when-to-use or when-not-to-use guidance. Usage is implied rather than explicitly stated.

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 idempotentHint=true and destructiveHint=false. The description adds beyond: costs gas (ETH), permanent on-chain record, and cannot be deleted even if bundle is purged. 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?

Every sentence earns its place: purpose, prerequisite, cost, idempotency, and return format. Bullet points and concise wording. Zero waste.

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 single parameter, annotations, and no output schema, the description covers all needed information: prerequisite, cost, idempotency, return shape, and permanence. Fully complete for the tool's complexity.

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

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

Schema coverage is 100% and the parameter is described in both schema and description. The description adds context about the prerequisite (bundle status 'complete'), which is not in the schema. This extra value justifies a 4 instead of 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?

The description clearly states the verb 'Notarize' and the resource 'evidence bundle on-chain by writing its manifest SHA-256 to the blockchain (Base/EVM)'. It distinguishes from siblings like get_bundle (status check) and verify_bundle (verification) by focusing on the on-chain writing action.

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: bundle status must be 'complete' and advises checking with get_bundle. Mentions idempotency and cost. However, does not explicitly state when not to use it or provide alternatives.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds the use of a 'quality AI model' and provides the exact return structure, including confidence levels and citations, which is valuable 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 includes a detailed inline JSON for the return value, which is informative but lengthy. It could be more succinct by referencing a schema or summarizing.

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

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

The description covers output structure but lacks details on error handling, limits beyond file size, or usage constraints. Given no output schema, the provided structure is helpful but incomplete for full tool 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 description coverage is 100%, so parameters are already well-documented. The description repeats the MIME types and max file size but adds no new semantic meaning beyond what the schema provides.

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

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

The description clearly states the verb 'parse' and the resource 'receipt or invoice document' into 'structured fields'. It differentiates from sibling extraction tools like extract_text by specifying the target and output format.

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 such as extract_structured or extract_text. The description does not mention exclusions or preferred 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 mark readOnlyHint and openWorldHint. The description adds 'Lean mode — no bundle stored' and explains return fields including truncation and confidence, providing 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?

The description is four concise sentences, each with a specific role: purpose, mode, alternative, and return format. No unnecessary words, front-loaded with key 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?

For a tool with 3 parameters, full schema coverage, and existing annotations, the description fully explains return values and behavioral nuances (truncation, citations). It is complete and leaves no critical 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%, so baseline is 3. The description adds value by explaining the return structure (e.g., 'truncated', 'confidence', 'citations') and clarifying that max_tokens truncates page content, not the answer, which aids agent 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?

The description clearly states 'Fetch a public HTTPS URL and answer a specific question about its content', providing a specific verb and resource. It distinguishes from the sibling 'ask_collection' by noting this tool is for single-document Q&A, while ask_collection is for 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?

The description explicitly tells when to use this tool (to answer a question from a single URL) and provides an alternative for multi-document scenarios. No further when-not-to-use is needed given the simplicity.

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. Description adds 'Free — no credits consumed' and details the async indexing prerequisite, which is behavioral info 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?

Six concise sentences that front-load the purpose, then provide prerequisites, usage guidance, and return format. Every sentence earns its place without unnecessary verbosity.

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 the return format. It covers prerequisites, alternatives, and free status. Lacks mention of pagination or vector-specific details, but these are minor for 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 baseline is 3. The description does not add parameter-specific details beyond what the schema already provides, but it does link collection_id to create_collection indirectly via the return format mention.

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, differentiating it from ask_collection which gives a synthesized cited answer.

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 mentions when to use search_collection vs ask_collection ('Use search_collection for raw matching chunks; use ask_collection for a synthesized cited answer.') and notes the prerequisite of populating the collection and waiting for indexing to complete.

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 details beyond annotations: output format, truncation strategy, and that max_tokens truncates input, not output. 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?

Well-structured with clear output example; slightly verbose but informative, front-loaded with purpose.

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

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

No output schema, but description details output structure and truncation. Simple tool (2 params) is well-covered.

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 description adds workflow context for text param and explains max_tokens behavior, enhancing 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?

The description clearly states it summarizes document text into a prose summary and key points, and distinguishes from sibling 'summarize_url' by specifying text input and workflow.

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/extract_url first), but does not explicitly exclude cases like using summarize_url for URLs.

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, indicating a safe read operation. The description adds context: it fetches a public URL, does not store any bundle (no side effect), and specifies the return shape (url, summary, key_points, truncated, word_count). This provides valuable behavioral clarity 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: two short sentences plus a return type annotation. Every sentence adds value without redundancy. The structure is front-loaded with the main action and then details.

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

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

For a relatively simple tool with two parameters and no output schema, the description covers the main purpose, return shape, and a key behavioral aspect (no storage). However, it lacks details on error handling (e.g., invalid URLs, network failures) and content type limitations (e.g., only HTML). Despite these gaps, it is fairly complete given the tool's simplicity and the presence of good annotations.

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

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

Schema description coverage is 100%, with both parameters well-documented: url is described as 'Public HTTPS URL to fetch and summarize' and max_tokens includes details on token-to-character ratio and truncation scope. The overall description does not add extra semantic meaning beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly states it fetches a public HTTPS URL and returns a prose summary with key points. It mentions 'Lean mode — no bundle stored' which distinguishes it from tools that store bundles. However, it does not explicitly differentiate from siblings like qa_url or summarize_document, relying on implicit differentiation.

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

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

The description implies usage for public URLs only and that no bundle is stored, providing some context. It does not explicitly state when to use this tool versus alternatives such as qa_url (for question answering) or extract_url (for raw extraction), nor does it mention prerequisites 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.

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

Annotations already declare readOnlyHint=true, and the description adds behavioral details: 'Lean mode — no bundle stored' (no persistence) and the return structure. This provides context beyond the annotations, though it could mention potential fetch failures or network dependency.

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 plus a return line—efficient and front-loaded. The first sentence conveys the core action, the second highlights the key differentiator (no bundle storage), and the return format is listed. No superfluous text.

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, annotations, and schema coverage, the description covers the main behavior and output. It could be more complete by addressing error conditions or explicitly linking to siblings, but it is sufficient for an agent to invoke 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 explicit descriptions for each parameter (url format, max_tokens explanation, target_lang examples). The description does not add further parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Fetch a public HTTPS URL and return its content translated') and the resource ('public HTTPS URL') with a specific outcome ('translated into a target language'). The phrase 'Lean mode — no bundle stored' distinguishes it from sibling tools that may store bundles, enhancing clarity.

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 usage for translation of URL content but does not explicitly state when to use this tool versus alternatives like extract_url, qa_url, or summarize_url. No exclusions or when-not-to-use guidance 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 indicate readOnlyHint and idempotentHint, confirming safe read-only operation. The description adds value by detailing the verification steps, return object structure, and cost (free). It also notes ownership requirement, which is 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 with two sentences and a structured return type block. It front-loads purpose and includes key details. The return type is valuable but slightly lengthens the description, so not a perfect 5.

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

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

For a simple tool with one parameter, the description is thorough: it explains purpose, what it checks, return format, cost, and ownership. It does not cover error cases or prerequisites beyond API key ownership, but that is acceptable given the tool's 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?

The single parameter bundle_id has a clear schema description ('Evidence bundle ID (ev_...) returned by extract or notarize'). The tool description reiterates this format, adding minimal extra meaning. With 100% schema coverage, baseline is 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?

The description clearly states it verifies cryptographic integrity of an evidence bundle, specifying what it checks (manifest hash, signature, artifacts). It distinguishes from sibling tools like get_bundle (retrieval) and notarize_bundle (creation) by focusing on 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?

The description implies usage for bundles owned by the user's API key and states it's free. However, it does not provide explicit guidance on when to use this tool versus alternatives like get_bundle or check_claims, nor does it mention 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.