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

Annotations declare destructiveHint=true and idempotentHint=true; the description adds concrete context beyond them — that null/empty deletes a language, that Obriym does not translate for MCP clients, that a warning is returned when the CRM lacks the language, and that the workspace is echoed back. No contradiction with the annotations.

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?

Dense but front-loaded: the core behavior (single-language write, null clears) leads, followed by prerequisites, the sibling contrast, and return behavior. Every sentence carries actionable information with no filler.

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?

Though there is no output schema, the description still discloses the meaningful return behavior (warning, echoed workspace) plus the translation and locale prerequisites. An agent has everything needed to invoke it correctly despite the mutation and cross-tool dependencies.

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 100%, so locale, brandId, and description are already documented in the schema (including the base-language exclusion and the NAME rule). The description reinforces these but adds little parameter syntax or format detail beyond what the schema states, so the baseline 3 is appropriate.

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+resource+scope: writing a brand's description in ONE language while leaving others intact. It draws the key boundary against update_brand ('translations field REPLACES the whole set, so use this tool to change a single language'), which an agent could not infer from the name alone.

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 and when-not: call list_content_locales first, base language is refused and routed to update_brand, and the sibling update_brand is named as the whole-set alternative. It also states a hard rule ('never translate a brand NAME') and the client-side translation responsibility.

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