Polytranslator

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe read operation. The description adds a meaningful qualifier ('purchased credit balance' as opposed to free or promotional credits) and clarifies the value is 'available to the API,' but it does not describe any further behavior such as caching, rate limits, or response units. With annotations carrying the safety profile, a 3 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 a single sentence with no filler words. It immediately states the core subject and provides a clarifying qualifier ('purchased' and 'available to the API'). Every word 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?

For a zero-parameter read-only tool, the description is nearly complete. It identifies what is returned (credit balance) and its scope (purchased, API-available). The only missing detail is the exact return format (e.g., integer, float, string), and no output schema exists to fill that gap, so a small deduction is warranted.

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 are zero parameters, so the schema carries no burden and the description does not need to explain parameters. The description itself adds semantic meaning beyond the empty schema by defining what the balance refers to. Baseline 4 is justified for a zero-parameter tool.

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 resource ('account's purchased credit balance') and the operation (available to the API), and it is obviously distinct from the sibling tools, which all involve documents or translation. Even though the sentence is a noun phrase rather than a verb, it unambiguously conveys that the tool retrieves credit balance.

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 no guidance on when to use this tool versus alternatives. There is no mention of checking credits before other operations, no prerequisites, and no stated conditions for use. The context signals show no siblings that compete directly, but the description still fails to provide any usage direction.

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 blocking behavior (waits up to wait_seconds), completion criteria, and that download links expire in 24 hours. Annotations already say readOnlyHint=true; description adds timeout and link validity 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, front-loaded with the tool's purpose and key behavioral trait (waiting). Every word 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 no output schema, the description notes completed documents include download links but doesn't describe the response format for pending/failed states. Still, for a status-checking tool with annotations covering idempotence, it is largely sufficient.

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 0%, so description must compensate. It explains document_id implicitly by referencing documents from translate_document and explains wait_seconds as the wait limit. Lacks explicit details like default wait behavior, but the core semantics are conveyed.

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 identifies the resource (document status), the action (get), and ties it to translate_document. It also distinguishes the tool from siblings like translate_document and translate_text by focusing on status retrieval.

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?

States it is for documents started with translate_document, implying when to use it. Could be stronger on when not to use it (e.g., for text translation status use translate_text), 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?

The annotations already convey read-only safety (readOnlyHint=true) and a closed language set (openWorldHint=false). The description adds useful behavioral context: the 474+ language count, partial name/code matching, and the first-100 default listing. However, it does not disclose response shape or pagination beyond the first 100, so the added behavioral context is moderate.

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?

A single front-loaded sentence carries the core operation and scope with zero filler. Every word contributes, and the optional-query behavior is left to the schema where it belongs.

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 read-only lookup with one optional, fully documented parameter, the description plus annotations and schema cover selection and invocation needs. The only gap is that no output schema exists and the description does not state the response fields, but this is a minor omission for such a straightforward listing 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% and the query parameter is already fully documented ('Part of a language name or code; omit to list the first 100'). The description's 'by name or code' merely restates the schema, adding no syntax, format, or edge-case detail, so a 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 states a specific operation ('search') on a precise resource ('the 474+ supported languages') with explicit search keys ('by name or code'). The title 'Find language codes' reinforces the result, and the operation is clearly distinct from the sibling translation/document/credit 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?

No guidance is provided about when to choose this tool over alternatives or when not to use it. The description implies a lookup use case, but it never names siblings or conditions, leaving the agent to infer the selection context.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds useful behavioral context: no translation is performed, no charge occurs, and the result can be compared with the account balance. This goes beyond the annotations without contradicting them.

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

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

A single concise sentence that front-loads the core purpose and includes the key non-behaviors. There is no redundant or filler content.

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 7-parameter tool with no output schema, the description provides enough context to understand the tool's role and result semantics: a credit price with no translation or charge. It does not describe return format details, but the schema covers the parameters and the description covers the essential behavior.

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 parameters are already well documented. The description adds general context about credits and balance but does not detail any parameters, which is acceptable given the schema's thoroughness.

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

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

The description uses a specific verb and resource: 'Price a document in credits.' It also explicitly states the tool does not translate or charge, which clearly separates it from translate_document and translate_text while reinforcing the 'free' title.

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 phrase 'without translating or charging anything' gives clear context that this is for obtaining a quote rather than performing translation. However, it does not explicitly name the alternative tools or state when not to use it, so it falls just short of full explicit guidance.

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

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

The description substantially enriches the sparse annotations (only readOnlyHint, openWorldHint, etc.) by disclosing billing behavior ('Charges the quoted credits once; failed documents are refunded'), size limits ('Up to 50 MB and 1,000 PDF pages'), and the asynchronous wait/fallback behavior. This is exactly the kind of operational context an agent needs.

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 main purpose and packs essential constraints (formats, limits, billing, async fallback) into three sentences. The enumeration of formats is somewhat list-heavy but necessary; no sentence is pure 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 9-parameter tool with no output schema, the description covers the critical operational aspects: input scope, output format, size limits, billing/refund, and async retrieval fallback. It only lightly gestures at the response shape ('returned id'), which would help an agent invoke the follow-up correctly, but the guidance is sufficient for basic use.

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 every parameter, including enums and defaults (e.g., 'formatted (default)', 'fast (default)'). The description adds broad context like file type limits and billing but does not clarify parameter syntax or requirements beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Translate a PDF...' and clearly enumerates supported input formats and the output behavior (same file type, layout preserved). This unambiguously distinguishes it from sibling translate_text (plain text translation) and quote_document/get_document (estimation and retrieval).

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 contextual guidance on async workflow: it waits up to wait_seconds and instructs calling get_document with the returned id if still running. This is an explicit alternative route for one condition. However, it does not explicitly state when to prefer this tool over translate_text or when not to use it, leaving a small gap.

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 only indicate non-read-only, non-destructive behavior. The description meaningfully adds the 50,000-character cap and credit-cost model (1 per 1,000 fast, 3 advanced), which are behavioral details an agent needs. It does not cover failure behavior or max_credits enforcement, but it adds solid value 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 tight sentences with no filler. The most decision-relevant facts—character limit and credit cost—are front-loaded, while tier pricing efficiently supports parameter choices.

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 5-parameter tool with no output schema, the description covers purpose and cost but omits expected response format, behavior when exceeding 50,000 characters or max_credits, and language code validation. It is adequate but has clear 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 60%, and the schema already documents target/source language and tier. The description adds cost semantics for tier and character count, but leaves max_credits' role and text length validation implicit, so it only partially compensates for the coverage gap.

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 as translating text, with a specific resource ('text') and a concrete limit (50,000 characters). It stops short of explicitly distinguishing itself from sibling translate_document, although the word 'text' vs 'document' implies the boundary.

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: translate plain text up to 50k characters, with tier and cost implications. However, it provides no explicit when-to-use guidance versus translate_document or list_languages, and no exclusions or alternative routing.

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