Skip to main content
Glama

Save translations an agent wrote

verbaly_write_drafts
DestructiveIdempotent

Save your own translations as drafts checked for params, tags and plural cases, written only for existing source keys and kept for human review before approval.

Instructions

Save translations you wrote yourself, so neither a catalog nor the state file is ever edited by hand. Each one is checked the way verbaly_translate checks a provider (params, rich tags and plural cases must survive), written only for keys the source catalog has, and marked as a draft awaiting human review. Existing translations are kept unless overwrite is set, which is how an outdated one gets rewritten. Approving is not a tool here: a human reads the drafts (verbaly_drafts lists them) and runs verbaly review --approve.

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": {
      "locale": "<locale>",
      "entries": "<entries>"
    },
    "name": "verbaly_write_drafts"
  }
}

Input Schema

NameRequiredDescriptionDefault
rootNoProject root holding verbaly.config (defaults to the server working directory)
localeYesTarget locale, one of the project's non-source locales
entriesYesThe translations, by catalog key
overwriteNoReplace translations that already exist, for example outdated ones

Output Schema

NameRequiredDescriptionDefault
keptYesAlready translated, left as they were (overwrite replaces them)
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
invalidYesRejected: empty, or the params, tags or plural cases were not preserved
unknownYesNot in the source catalog, so nothing was written
writtenYesSaved as drafts, a human still has to approve them

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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"
      +}
  2. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Rich context beyond the annotations: it discloses the validation gate (params, rich tags, plural cases), the key-existence restriction, the draft-awaiting-review state, and the keep-unless-overwrite default that makes destructiveHint=true legible. What it leaves out is failure behavior — whether one invalid entry aborts the whole batch or partially writes — which matters for a destructive mutation.

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?

Three front-loaded sentences that move from what to how to what is out of scope, with no filler. The final sentence is longer than needed but carries the important handoff to the human review step.

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

Completeness4/5

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

An output schema exists, so return values need no explanation, and the description covers the mutation's preconditions and side effects well. It falls short only on atomicity and error surface, which an agent calling a destructive batch write would benefit from knowing.

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, and the description goes beyond it by stating that entries are written only for keys the source catalog has and that overwrite is the mechanism for rewriting outdated translations. The root, locale, and entries shape are otherwise already covered by schema descriptions.

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?

States a precise verb+resource: saving agent-authored translations as drafts. It immediately distinguishes the tool from verbaly_translate (provider translations that are checked the same way) and from verbaly_drafts (which lists drafts for human review), so an agent can tell the siblings apart without opening schemas.

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 frames the use case ("translations you wrote yourself") and rules out a likely wrong assumption by stating approval is not a tool here and pointing to the human `verbaly review --approve` path. It also names verbaly_drafts as where the resulting drafts surface.

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