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

With no annotations supplied, the description fully discloses key behaviors: local disk reading, upload to Differino, 45 MB limit, signed URL uploads, credit consumption, async status, and polling. It also explains what each mode returns, including page images and metadata.

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

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

The description is appropriately detailed without fluff; each sentence adds a distinct fact. The first sentence defines purpose, followed by upload process, size, modes, async handling, and cost—logical flow.

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 or annotations, this description covers all essential operational aspects: file types, size, modes, polling behavior, and credit consumption. It leaves no critical gaps for an agent to invoke the tool successfully.

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, so baseline is 3. The description adds meaningful context for comparison_mode by linking 'visual' to a full manifest with page images and 'text' to faster text-only output, plus file size limits beyond the schema. This elevates the value.

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

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

Clearly states a specific action: 'Compare two documents (PDF, DOCX, or TXT) and see the differences.' It names supported file types, mentions upload to Differino, and distinguishes from siblings by implying it creates a new comparison rather than retrieving existing ones.

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 mode guidance (visual vs text) and directs the agent to poll get_comparison when status is 'processing.' However, it does not explicitly contrast with sibling tools like get_text_diff or list_comparisons, despite the workflow being implied.

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?

With no annotations provided, the description carries the full burden and does an excellent job. It discloses the 5-minute URL validity, 2-second polling interval, 3-minute timeout, return shapes for both wait values, the readiness prerequisite, watermarking policy based on credits, and the fact that no credits are consumed.

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 information-dense, with no filler. It front-loads the main purpose and then succinctly explains the two wait modes. Each sentence earns its place 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 having no output schema, the description provides comprehensive context: return objects for both wait settings, prerequisites, polling details, watermark differences, URL expiration, and credit impact. This fully equips an agent to use the tool correctly for a complex export operation.

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

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

The schema covers all 4 parameters at 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the wait parameter in depth (polling behavior, return payloads) and the prerequisite on comparison_id. It does not rehash locale or include_unchanged, which are already self-explanatory in 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 a specific verb+resource: "Export a finished comparison as a PDF report and return a temporary download URL." It distinguishes itself from sibling tools (e.g., get_text_diff, summarize_visual_diff) by focusing on PDF export rather than inline diff or summary output.

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

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

The description gives clear usage context: it requires the comparison to have status="ready", and it explains the two wait-mode workflows (blocking with polling vs. immediate return). It does not explicitly name alternative tools or when-not-to-use, but the context is sufficient for correct selection.

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?

With no annotations, the description carries the full burden. It discloses a key behavioral trait: 'Does not consume credits.' It also implies read-only nature and provides context about error handling (NO_CREDITS). This is solid coverage for a simple tool, though it does not mention potential rate limits or other failure modes.

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

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

The description is front-loaded with the core purpose, followed by usage context and a crucial note about credits. It is compact, every sentence adds value, and there is 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 parameterless tool with no output schema, the description sufficiently conveys the return fields and the main use cases. It includes workspace ID, balance, plan, and free comparison status, which are the essentials. It could explicitly list all return fields, but the provided info is sufficient for an agent to understand and invoke the tool.

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

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

The tool has zero parameters, and the schema coverage is 100% (empty schema). The description adds value by explaining what the response contains (credit balance, free comparison availability, plan, workspace ID), which is more than 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 tool's function: getting account status including credit balance, free comparison availability, plan, and workspace ID. This is specific and distinct from sibling tools like compare_documents or export_comparison_pdf, which focus on document operations.

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

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

Explicit usage guidance is provided: use before compare_documents to ensure payment capability, or after a NO_CREDITS error to confirm balance and obtain a purchase URL. This gives clear context but does not explicitly mention when not to use it relative to other siblings, though the separation is evident from purpose.

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?

With no annotations provided, the description carries the full burden. It discloses that results may include processing status (polling), that signed URLs are refreshed, that visual artifacts may or may not be available, and that the operation does not consume credits. These are meaningful behavioral traits beyond the bare 'get' operation.

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, front-loaded with the core purpose, and every clause adds useful information. There is no repetition of schema fields or fluff; the second sentence gives actionable usage guidance. Highly concise and well-structured.

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

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

For a simple single-parameter tool with no annotations and no output schema, the description covers the key aspects: what it returns (including conditional visual data), when to use it (polling and re-fetching), and cost behavior. It is sufficiently complete for an AI agent to select and invoke the tool correctly.

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

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

The input schema fully documents the only parameter (comparison_id as UUID, 100% coverage). The description merely references 'by its ID' without adding any new semantic detail about the parameter itself. Baseline 3 is appropriate because the schema already handles this.

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

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

The description opens with a specific verb-resource pair ('Get the status and results of a specific comparison by its ID') and elaborates on the exact contents (visual.status, visual.manifest contract, grouped change identities, salience metadata). This clearly distinguishes it from sibling tools like list_comparisons or get_text_diff.

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

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

The description explicitly states when to use the tool: 'to poll a comparison that is still processing, or to re-fetch results (including fresh signed URLs) for an existing comparison.' It also notes 'Does not consume credits,' which is a relevant selection factor. It does not name alternatives or provide explicit when-not guidance, so it misses the '5' threshold.

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?

With no annotations, the description carries full behavioral disclosure. It describes the return format, default filtering behavior, ability to include equal blocks, support for both text and visual comparisons, and explicitly states 'Does not consume credits.' This goes well beyond the minimal requirement.

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 three sentences, front-loaded with the core purpose, then details, then usage guidance. Every sentence contributes unique information with no redundancy or 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?

Despite having no output schema, the description thoroughly explains the return structure and behavior. It covers prerequisites ('finished comparison'), parameter behavior, credit implications, and text vs. visual support, making it complete for an API with 3 well-documented parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a small amount of value by explaining the default behavior of only_changed and the use case for setting it to false, but it does not provide deeper semantics beyond what the schema already documents.

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 identifies the tool's function: fetching block-level text diff of a finished comparison, including specific output details (summary counters, diff blocks, word-level spans). This distinguishes it from siblings like summarize_visual_diff or get_comparison by focusing on exact text changes.

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

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

The description provides clear usage context with 'Best when you need to quote exact text changes' and notes it works for both text and visual comparisons. It does not explicitly name alternative tools or state when not to use it, but the guidance is sufficient for selection.

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?

With no annotations, the description carries the full burden. It discloses return fields, ordering, status filtering, and that it does not consume credits. It does not mention pagination behavior beyond the limit parameter, but the limit is in the schema, so this is adequate.

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

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

Two sentences, front-loaded with purpose, then details. Every sentence earns its place, and the information density is high without being verbose.

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

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

For a simple list tool, the description is complete. It covers the return fields, ordering, status filter, use cases, and credit cost, making it sufficient for an agent to decide when and how to invoke the tool.

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

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

Schema description coverage is 100%, so both parameters are already well-documented. The description adds a small note about using status to find unfinished comparisons, but does not add substantive meaning beyond the schema.

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

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

The description states the verb ('List'), resource ('comparisons'), and scope ('in the workspace, newest first'). It distinguishes from siblings by focusing on listing recent comparisons vs. getting a single comparison or exporting PDF.

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

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

Explicitly states use cases: 'find a comparison id when you do not have one, to check recent activity, or to locate unfinished comparisons (status filter).' This implies when not to use it (when you already have an id, use get_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?

With no annotations, the description carries the full burden. It discloses key behavioral traits: deduplication by groupId, no image URLs/coordinates, prerequisite status, and that it does not consume credits. It stops short of error behavior or side effects, but is substantially transparent.

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

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

The description is dense but each sentence earns its place, covering purpose, deduplication, output constraints, salience ordering, prerequisite, alternative, and cost. It is front-loaded with the core purpose and avoids 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 and no annotations, the description fully specifies what the tool returns (one entry per change group with type, title, salience, snippets), what it omits (image URLs, coordinates), and when it is applicable. This is complete for an agent to decide whether to invoke it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining min_salience with the prominence order and framing the tool as the cheapest way to reason about changes, which helps parameter selection. The other parameters are well-covered by the schema descriptions.

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

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

The description states a specific verb ('summarize') and resource ('visual diff of a finished visual comparison'), and clearly distinguishes from siblings by explicitly naming get_text_diff for text-mode comparisons. It also explains the unique output characteristics (page-by-page, deduplicated groups).

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

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

The description explicitly says when to use it (finished visual comparison, visual.status='ready') and when not to (text-mode comparisons, use get_text_diff instead). It also mentions it is the cheapest way, helping the agent weigh it against alternatives.

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