expand_multilingual

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is known. The description adds valuable behavioral detail: it discloses that a failing locale reports its error field and does not affect other locales, which is useful for handling partial failures. This goes beyond 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?

The description is compact: two sentences plus a focused note on locales. It front-loads the primary purpose and provides essential parameter details without unnecessary wording. Every sentence contributes to understanding tool behavior.

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?

The description gives the core behavior, locale syntax, defaults, and error handling. Since an output schema exists, return values are not needed. It does not mention the 'source' parameter, but the schema's enum clarifies its options. For a tool with moderate complexity, this is nearly complete.

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?

With 0% schema description coverage, the description must compensate. It thoroughly explains the 'locales' parameter with format and default values, and 'keyword' is implied as the seed. However, it does not add any meaning for the 'source' parameter, which has an enum but no additional guidance. The description covers only one of three parameters substantively, so it only partially compensates for the schema gap.

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?

The description states a specific action — "Run one seed through autocomplete" — and a distinctive scope: "several locales at once." This clearly distinguishes it from sibling expand tools like expand_alphabet or expand_questions, and from suggest, which likely handles a single locale.

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 description implies when to use it: when you need autocomplete expansion across multiple locales simultaneously. It provides default locales and clarifies that a failing locale doesn't break others, giving practical context. However, it does not explicitly compare with alternatives or state when not to use it, so it's a step below the explicit routing seen in the best examples.

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