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

With annotations only covering safety flags (non-readonly, non-destructive, closed-world), the description carries the real behavioral load: writes are staged as suggestions the author must accept/decline before publish, respondents keep seeing the published version, the language row is auto-created, and a single bad entry rolls back the whole batch.

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?

Front-loaded with the operation and its atomicity guarantee, then the suggestion/publish consequence, then a guardrail. Dense and mostly economical, though the bolding and three-paragraph layout is slightly heavier than needed.

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?

A complex batch mutation with no output schema, no annotations beyond safety flags, and a nested array parameter — the description covers atomicity, validation/rollback, side effects, staging model, and auto-creation of languages, which is everything an agent needs to invoke it 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?

Top-level schema coverage is reported as 0%, so the description must compensate: it explains that entries is a batch of key/language/value objects, that a one-item array performs a single-key edit, and that upsert semantics apply (new keys/languages allowed). It does not explain formId or the sourceHash staleness workflow, which the nested schema documents instead.

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?

States a specific verb and resource ("Upsert one or more translation entries across one or more languages in a single atomic mutation") and clarifies it covers both single-key edits and bulk language writes. Clearly separable from translationDraft_get and translationDraft_publish 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.

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

Explicit when-to-use guidance: "this is how you translate into a language the form does not have yet", "Works from any page", "Pass a one-item array for a single-key edit". It also states an exclusion ("Do not change the form's source language or edit form content as a substitute for translating"), leaving little inference.

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