Import translated texts

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

With no annotations at all, the description carries the full burden and does well: it discloses the safe-by-default write posture, the skip semantics, automatic splitting of long dialogue into multiple message boxes with choices kept in sync, and control-code mismatch warnings. It stops short of saying whether changes land inside a changeset (begin_changeset/commit_changeset exist as siblings) or whether a backup is taken, which matters for a bulk mutation.

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-loads the riskiest fact (dry run by default) in the second clause, then layers skip rules, splitting behavior, and warnings in descending order of importance. Dense but every sentence carries a distinct behavioral fact; nothing is restated from the title.

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 3-parameter bulk-write tool with no annotations and no output schema, the description covers the safety model, row-level filtering, and structural side effects well. The remaining gap is what the dry-run report actually contains and how it interacts with the project's changeset/backup machinery, which an agent would want before committing a large import.

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 67% and the undocumented parameter is dryRun, whose meaning the description fully supplies (default true, read-only report, writes only on false). It also elaborates force beyond the schema's one-liner by explaining that it overrides the original-text mismatch guard. The file path parameter is left to the schema, which documents it adequately.

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 ('Apply the translation column ... back into the project's data') and ties itself to the paired sibling export_texts, which makes the import/export pair unambiguous. An agent can distinguish this from export_texts, bulk_update_records, or update_record 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.

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

Gives clear operating conditions: dry run is the default and nothing is written until dryRun=false, empty rows are skipped, and stale rows are skipped unless force=true. It implies the precondition that the file comes from export_texts but never states an explicit exclusion or prerequisite ordering (e.g. re-export instead of forcing).

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