Skip to main content
Glama

Machine-translate missing entries

verbaly_translate
Idempotent

Fill missing translations using the configured provider and save each new translation as a draft for human review; use dryRun to list what would be translated without calling the provider.

Instructions

Fill missing translations with the configured provider (what verbaly translate does). The default provider is Claude, which needs @anthropic-ai/sdk and ANTHROPIC_API_KEY. Every new translation is saved as a draft awaiting human review (verbaly review), which no tool here can approve. Each language is saved as soon as its last batch lands, so a run that is cut keeps the languages it finished. A batch the provider never answers, or a language whose file cannot be saved, is reported in failed and everything else stays written, so a retry only asks for what is left. dryRun lists what would be translated without calling the provider. A locale the project does not have is an error that lists the ones it has, never an empty result. To see what is missing first, use verbaly_missing; to save translations you wrote yourself, verbaly_write_drafts.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "verbaly_translate"
  }
}

Input Schema

NameRequiredDescriptionDefault
rootNoProject root holding verbaly.config (defaults to the server working directory)
dryRunNoList missing entries per locale, call no provider
localesNoTarget locales (default: all)

Output Schema

NameRequiredDescriptionDefault
keptYesWritten on disk by someone else while the provider worked, so left as they were
lockNoThis run created verbaly.lock, moved an older state file (from) into it, or rewrote it whole after a merge conflict (merged): it belongs in git with the catalogs, so tell the user to commit it
dryRunYes
failedYesBatches the provider never answered and languages that could not be saved, safe to retry
invalidYesRejected: params or tags were not preserved
pendingYesdryRun only: what would be translated
translatedYesSaved as drafts, a human still has to approve them

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.86.0
    • changedOutput schema / properties / failed / description
      Previous value: -"Batches the provider never answered, safe to retry"New value: +"Batches the provider never answered and languages that could not be saved, safe to retry"
  2. Changed1 schema field changedv0.82.0
    • addedOutput schema / properties / lock
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "This run created verbaly.lock, moved an older state file (from) into it, or rewrote it whole after a merge conflict (merged): it belongs in git with the catalogs, so tell the user to commit it",
      +  "properties": {
      +    "file": {
      +      "type": "string"
      +    },
      +    "from": {
      +      "type": "string"
      +    },
      +    "merged": {
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "file"
      +  ],
      +  "type": "object"
      +}
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations: requires the @anthropic-ai/sdk and ANTHROPIC_API_KEY, output lands as drafts awaiting review, each language commits independently so interrupted runs keep finished locales, and failures are surfaced in `failed` while the rest stay written. The idempotentHint=true annotation is corroborated by the statement that a retry only asks for what is left, and openWorldHint=true is consistent with calling an external provider.

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 with purpose and the provider requirement, then failure semantics, and finishes with sibling routing. Nearly every clause carries operational information, though the middle section is a dense chain of run/failure conditions that could be split for faster scanning.

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?

For a network-dependent, partially-committing write tool, the description covers prerequisites, atomicity per locale, failure reporting, dry-run behavior, and the human-review gate. With an output schema present, return shapes need not be explained, so nothing an agent needs is missing.

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 baseline is 3. The description still adds meaning beyond the schema for `locales`: an unknown locale is an error that enumerates valid locales rather than returning an empty result, which tells the agent how validation fails. dryRun is essentially restated, but the locale error contract is genuine added value.

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?

Opens with a specific verb+resource ('Fill missing translations with the configured provider') and anchors it to the CLI equivalent. It also distinguishes itself from the two nearest siblings by name, so an agent can pick it over verbaly_missing and verbaly_write_drafts without opening a 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?

Explicitly routes the agent: use verbaly_missing to inspect gaps first and verbaly_write_drafts for hand-written translations, implying this tool is for generating drafts via the provider. It also sets a hard boundary ('no tool here can approve' drafts), telling the agent what this call cannot accomplish.

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