Vaquill

Translate Text

translate_text

Translates a piece of text and returns it in the same response.

Charged in pages. See the cost rules below. A failed translation is refunded in full.

Authentication: a vq_key_ key holding translate:write. A wildcard (*) key does not hold it: grant it by name in the dashboard.

Pages, not characters

This product bills pages. A page of text is 2,000 characters, and the cost is ceil(characters / 2000).

Characters	Pages
1 to 2,000	1
2,001 to 4,000	2
50,000	25

Any non-empty text costs at least 1 page. Unlike the dashboard, there is no free floor on SIZE here: a 10-character request spends a page. Empty or whitespace-only text is a 422 and costs nothing.

That is about size, not about your allowance. Your account's monthly free pages are spendable through the API, and a charge draws on them first, so a short request can still cost you nothing out of pocket.

When you are charged and when you are not

Everything that can be checked up front is checked BEFORE the charge, and a refusal costs nothing: an unsupported language (read GET /translation/languages instead of hard-coding it), text over 50,000 characters (a 422, never a truncation) and empty text.

If your balance cannot cover the pages you get a 402 and nothing is translated.

Once charged, if the translation fails or comes back empty the pages are refunded and you get an error. You are never billed for a translation you did not receive.

Retries

Send an Idempotency-Key header. A retry of the same request with the same key returns the original response and does not charge again.

Limits

Text is at most 50,000 characters, because this route holds the connection open while the translation runs. Anything longer belongs on the document routes.

Example

curl -X POST https://api.vaquill.ai/api/v1/translation/translations \
  -H "Authorization: Bearer $VAQUILL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"text": "The petitioner submits that the impugned order is contrary to law.", "targetLanguage": "hi", "sourceLanguage": "en"}'

{
  "translatedText": "याचिकाकर्ता का निवेदन है कि आक्षेपित आदेश विधि के विरुद्ध है।",
  "detectedLanguage": "en",
  "targetLanguage": "hi",
  "pagesCharged": 1,
  "charCount": 66
}

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "text": "<text>",
      "targetLanguage": "<targetLanguage>"
    },
    "name": "translate_text"
  }
}

Input Schema

Name	Required	Description	Default
`text`	Yes	The text to translate, 1 to 50,000 characters. Longer is a 422, never a silent truncation; use the document routes for longer work. Whitespace-only text is a 422.
`sourceLanguage`	No	Language of `text`, or `auto` (the default) to detect it.	auto
`targetLanguage`	Yes	Language to translate INTO. A code from `GET /translation/languages` with `target: true`. `auto` is not a target. Regional tags are narrowed, so `hi-IN` is read as `hi`.
`Idempotency-Key`	No	Optional. 16 to 255 visible ASCII characters (a UUIDv4 is ideal). A retry with the same key and the same request replays the original 2xx response for 24 hours without charging again. The same key with a different request is rejected. Scope is the API key, method, path and body. The stored response body is a query-derived cache controlled by the account's data retention setting cacheQueryDerivedData: when it is false the body is never stored and a retry answers 409 idempotency_replay_unavailable, without charging again.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 6, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Goes well past the annotations: it discloses the billing model (pages = ceil(chars/2000), minimum 1 page, non-empty text costs something, empty text is a free 422), the scope required (`translate:write`, wildcard keys rejected), the 402 on insufficient balance, and full refunds on failed or empty translations. This is unusually rich behavioral context for a mutating, billed operation. It stops short of describing response payload fields, but an output schema exists, so that is covered elsewhere.

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

Conciseness4/5

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

Front-loaded (what it does, then cost, then auth, then limits) and sectioned with headings, which makes a long description skimmable. There is some redundancy: the character-to-page table repeats the `ceil(characters / 2000)` formula directly above it, and the JSON sample response duplicates what the output schema already declares.

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

Completeness5/5

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

Covers everything an agent needs before calling a billed translation endpoint: cost model, auth scope, pre-charge validation failures (422), insufficient-balance 402, refund guarantees, and idempotent retry behavior. With annotations and an output schema also present, no material gap remains.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already defines all four parameters, but the description adds real meaning beyond it: the cost consequence of `text` length (pages math), the reason for the 50,000-character ceiling (the connection is held open), and the retry contract behind `Idempotency-Key`. These are decision-relevant semantics the parameter descriptions do not carry.

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

Purpose5/5

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

"Translates a piece of text and returns it in the same response" states a specific verb and resource and adds the key scope detail that the result is returned inline rather than as a document. It also routes long inputs away from this tool ("Anything longer belongs on the document routes"), so an agent can separate it from the document-oriented siblings without opening the schema.

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

Usage Guidelines5/5

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

Explicit when-to-use and when-not-to-use: short text here, longer text (over 50,000 characters) on the document routes. It also tells the agent to resolve language codes via `GET /translation/languages` (the list_languages sibling) rather than hard-coding them, and states that `auto` is not a valid target.

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

All Vaquill tools Inspect

Try in Browser