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

Annotations only say readOnly=false, destructive=false, idempotent=false; the description adds genuinely useful behavior — nothing goes live, results land in a draft change set, and publishing happens in the admin panel, plus the override rule for manual vs machine translations. The main undisclosed trait is what repeated calls do given idempotentHint=false, i.e. whether each call creates a separate draft change set.

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?

Two sentences, zero padding, with the core action stated first and the side-effect semantics second. Nothing in it restates the tool name or title superfluously.

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 5-parameter write-shaped tool with no output schema, the definition covers what is produced (a draft change set) and what happens downstream, which is what an agent most needs. It stops short of specifying the response shape or draft-collision behavior on repeated calls, but that is a minor gap given the schema's field-level documentation.

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 already 80%, so the schema carries most parameter meaning; the description still adds that at least one of name or description should be supplied ("name and/or description"), which the required list does not enforce. It does not elaborate on entity/entity_id/locale beyond what the schema states.

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?

"Propose a translation (name and/or description) of one product or category into one menu language" names a specific verb (propose), the exact resource (a translation of a product/category's name or description), and the scope (one entity, one locale). This distinguishes it cleanly from siblings like draft_product_description or draft_site_text, which draft source copy rather than a locale-targeted translation.

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?

The second sentence establishes the working context: output is a draft change set that the owner must review and publish, and manual translations supersede machine output once published. That tells an agent when this tool is the right choice (pre-publication drafting) without explicitly naming alternatives or stating exclusions such as when to prefer menu_audit for detecting missing translations.

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