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

With no annotations, the description carries the full behavioral burden. It usefully discloses batching semantics ('writes once per locale file') and the non-obvious locales filter behavior (other locales in entries are ignored) — a real side-effect worth flagging. However, it never says what happens to existing keys on update, whether writes are destructive/overwriting, or what the call returns.

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?

Three tight sentences, front-loaded with the core operation and followed by the efficiency rationale and the filter nuance. Little waste, though 'More efficient than repeated add_translation calls' overlaps with 'Prefer this for bulk work.'

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 mutation tool with no annotations, no output schema, and two undocumented parameters, the description should clarify conflict/overwrite behavior and results. It covers bulk semantics and the locales filter adequately but leaves the namespace/entries contract and update side effects unspecified.

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 only 33%, so the description is expected to compensate. It does add genuine meaning for the locales filter ('others in translations are ignored'), going beyond the schema text. But namespace and the nested entries/translations structure are left undocumented in both schema and description.

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 pair (add or update), a specific resource (translation keys), and the scoping trait (multiple, in one operation). It also names the sibling it supersedes (add_translation), so an agent can distinguish it from the single-key variant without opening either 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?

Explicitly routes bulk work here and names add_translation as the repeated-call alternative, which is clear when-to-use guidance. It stops short of stating when NOT to use it (e.g. a single key), so it does not hit the full when/when-not/alternatives bar.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses upsert semantics and the partial-write guarantee ("other locales are unchanged"), which is real value beyond the schema. It omits what happens to an existing value being overwritten, whether the namespace must pre-exist, and any auth or error behavior.

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?

Three short sentences, front-loaded with the action and immediately followed by the key format and the write-scope caveat. Every sentence contributes; no padding or redundancy.

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-required-param mutation tool with no annotations and no output schema, the description covers the core semantics (upsert, partial locale write) but leaves the namespace parameter and overwrite/error behavior unaddressed. Adequate but with clear gaps.

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 description largely restates the key's dot-notation format already documented in the schema. It does add locale-scope meaning to the translations map ("across one or more locales", "only the provided locales are written"), but the namespace parameter remains undocumented in both places. 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 pair (add/update) and resource (translation key), and the word "single" implicitly distinguishes it from the sibling add_multiple_translations. It stops short of naming that sibling explicitly, but an agent can tell the two apart from the text 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?

The phrase "add or update" communicates upsert intent, which is useful for deciding when to call it, and the note that only provided locales are written helps scope the action. However, no sibling is named as an alternative (add_multiple_translations, copy_from_primary) and no prerequisites or exclusions are given, so usage is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Compare' implies a non-mutating read and the return contents are spelled out, but it never explicitly confirms read-only behavior, nor mentions cost/scope limits on scanning all locale files.

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?

Three sentences, zero filler, and the core action plus return contents are front-loaded before the optional-scoping note. Every sentence earns its place.

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?

With no output schema, the description correctly compensates by enumerating the return data (missing keys, extra keys, empty values per locale). Safety profile and any scoping/perf caveats are the only omissions, which are minor for a comparison check.

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% and the schema itself calls namespace 'optional', but the description adds the meaningful default that omitting it checks all configured namespaces. That behavioral default is not derivable from the schema alone, so it adds genuine value over the baseline 3.

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: compares locale files against the primary locale and returns a defined diagnostic set (missing/extra/empty values). It is clearly distinguishable in spirit from siblings like check_translation_quality or find_untranslated_values, but it never names an alternative to route against, so it stops short of full sibling differentiation.

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 only guidance is 'Omit namespace to check all configured namespaces', which is parameter usage rather than when-to-use. There is no explicit statement of when this audit should be chosen over find_untranslated_values or check_translation_quality, leaving the agent to infer from the purpose text.

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

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

With no annotations, the description carries the full burden, and it does disclose the key behavioral trait: the exact classification rules for each returned issue type, including the 30%/15-char 'short' threshold. It's silent on permissions, and being a read-style check it doesn't need to warn about mutation, so the main gap is minor.

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?

Purpose is front-loaded in the first sentence, followed by the return-value taxonomy, and the closing usage cue. The parenthetical definitions are dense but each earns its place by defining output semantics absent from any schema.

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?

Since there is no output schema, the description rightly carries the return-value explanation and does so with concrete issue definitions. Combined with 100% schema coverage of inputs, the definition is complete enough to invoke correctly, with only permission/read-only context left implicit.

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 description coverage is 100%, so both 'namespace' and 'keys' are already documented (including the dot-notation format). The description's 'for specific keys' merely echoes the schema without adding syntax or constraint detail, making baseline 3 correct.

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 ('Check translation quality for specific keys') and enumerates the three issue categories it detects. It gestures at sibling differentiation via 'instead of scanning the full namespace' but never names check_translation_integrity or find_untranslated_values, so an agent must still disambiguate among overlapping siblings.

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?

'Use this for targeted quality checks instead of scanning the full namespace' gives a clear context and an implicit alternative scope. However it doesn't name the specific sibling tool it displaces, nor state when this is the wrong choice, so the routing cue is directional rather than precise.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses one behavior - 'Returns an error if any key is missing from the primary locale' - but omits key mutation traits: whether target locales are overwritten, permission requirements, or reversibility for a write operation.

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?

Three tight sentences, front-loaded with the operation, then intent, then the error condition. Every sentence earns its place with no redundancy.

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 mutation tool with no annotations and no output schema, the description covers purpose, intent, and an error edge case. It falls short only on overwrite semantics, but is otherwise complete enough to call 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?

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description adds only the 'verbatim' semantics of the copy; it contributes no syntax or format detail beyond the schema. 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 (copy) and resource (primary locale value to target locales for given keys) with the manner ('verbatim'). It is clear enough to distinguish from write-oriented siblings like add_translation, though it never names an alternative explicitly.

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 concrete when-to-use guidance: 'Use for brand names, prices, percentages, and other terms that legitimately should not be translated.' This tells the agent the intent well, but offers no exclusions or named alternatives (e.g. add_multiple_translations for real translations).

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

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

With no annotations, the description carries the full burden, and it does disclose the destructive breadth ('from all locale files'), which is genuinely useful. However, it omits whether the removal is reversible, whether a missing key errors or is silently ignored, and any permission or confirmation requirements expected of a delete operation.

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?

A single front-loaded sentence with zero filler; the destructive scope is stated immediately rather than buried.

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 two-parameter destructive tool with no annotations and no output schema, the description covers the core action and its blast radius but leaves the namespace parameter, failure behavior, and reversibility unaddressed.

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 50%: 'key' is documented as a dot-notation path, but 'namespace' is undocumented in both schema and description, leaving the agent to infer its meaning. The description echoes both parameter names without adding format or constraint details beyond the schema.

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 precise verb ('Remove') and resource ('a translation key') plus a distinguishing scope ('from all locale files in a namespace'), which separates it from get_translation, add_translation, and the read-only siblings. It stops short of naming an alternative, but the destructive cross-locale scope makes the tool's identity unmistakable.

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?

There is no guidance on when to use this versus add_translation or the integrity/quality check tools, and no prerequisites or cautions. The agent must infer usage entirely from the verb.

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

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

With no annotations, the description carries the burden and delivers real behavioral context: it discloses the doNotTranslate exclusion rule and the exact return shape, which matters since no output schema exists. It stops short of stating read-only/side-effect-free status or permission requirements, so it isn't fully complete.

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?

Three tight sentences, front-loaded with the core definition, then the exclusion rule, then the return format. Every sentence adds distinct information with no redundancy.

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 two-parameter read tool with no output schema, the description is nearly complete: it explains the detection logic, the exclusion, and the return structure. It lacks only explicit read-only/permission framing and any note on scale or performance.

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 description coverage is 100%, with both parameters (locale, namespace) fully documented in the schema, so the baseline is 3. The description adds no parameter-level detail (e.g. locale default semantics or namespace resolution) beyond what the schema already provides.

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 precise verb+resource and defines the exact detection heuristic: keys whose translated value equals the primary locale value (placeholder translations). This is specific enough that an agent can distinguish it from sibling tools like get_pending_translations or check_translation_quality without opening schemas.

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 the tool is useful (locating stale placeholder translations), but never explicitly names alternatives or states when-not-to-use it, even though siblings like get_pending_translations and check_translation_integrity overlap conceptually. Usage is inferable but not guided.

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

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

With no annotations, the description carries full disclosure burden and does surface a genuinely important behavioral trait: the server resolves paths from its own root, not the caller's current directory. Read-only nature is only implied by "Report," and it does not state auth requirements or side-effect guarantees, leaving some gap for an unannotated tool.

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, no waste, with the return contents front-loaded and the worktree/cwd caveat following. The em-dash clause explains the mechanism rather than padding.

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?

There is no output schema, so the description must describe the return value—and it does so thoroughly (root, origin, config path, absolute path, structure, locales per namespace). Combined with the path-resolution caveat, an agent has everything needed to call 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?

The tool takes zero parameters, so per the baseline a 4 is appropriate. The description correctly implies a parameterless call, and there is no parameter surface for it to elaborate on.

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 gives a specific verb ("Report") and enumerates precisely what it reports: resolved project root, its origin, config file path, and the absolute path/structure/locales of every namespace. The purpose is unmistakable and clearly distinct in nature from the translation CRUD siblings, though no sibling is named to explicitly route the agent elsewhere.

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?

It gives an explicit triggering condition: "Call this before writing if you are working in a git worktree or any checkout other than the directory the MCP client was launched in." That is strong, actionable context, but there is no guidance on when NOT to call it and no alternative tool is named.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the result is keys only (no values), sorted, and drawn from the primary locale. Read-only intent is evident from 'Return'. It does not mention pagination or behavior for a missing/empty namespace, so it's strong but not exhaustive.

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, front-loaded with the return contract and followed by the motivating use case. Every clause earns its place with no redundancy.

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 simple single-parameter read tool with no output schema and no annotations, the description covers what is returned (sorted key list, no values) and why. Only minor gaps remain (pagination, empty/missing namespace handling), which are unlikely to block correct invocation.

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% and the single 'namespace' parameter is already documented as coming from .i18n-mcp.json, so the schema does the heavy lifting. The description adds only the context that keys come from the primary locale, not new meaning about the parameter itself. Baseline 3 applies.

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 ('Return a sorted list of all dot-notation keys in a namespace') plus a key scoping qualifier ('from the primary locale ... without their values'). The 'without their values' phrase implicitly separates it from value-returning siblings like get_translations, so an agent can route correctly without opening schemas.

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?

'Use this to plan batch translation work — avoids blowing context with full locale values across many locales' gives a clear use case and the reason to prefer it. It stops short of explicitly naming the alternative tool (e.g., get_translations) for when values are actually needed, so it's clear context without exclusions.

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

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

With no annotations, the description carries the burden and does well: it discloses the exact result shape, the doNotTranslate exclusion rule, and the size cap with an explicit continuation pattern. It does not cover permissions, error behavior, or confirm the read-only nature outright, so it falls just short of fully rich disclosure.

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?

Four tight sentences with no filler: purpose and return shape first, then exclusion rule, then the routing guidance, then the pagination/continuation behavior. Every sentence earns its place.

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?

There is no output schema, so the description must explain return values, and it does ({ key: primaryValue }), plus the exclusion and size-cap behavior. It is nearly complete; only edge cases such as a locale with no pending work or invalid namespace are unaddressed.

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 description coverage is 100% and both required params (locale, namespace) are documented in the schema with examples. The description only restates that the call is scoped to a single locale, adding no format, default, or constraint information beyond the schema; baseline 3 applies.

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 ('Get the complete translation work list for a single locale') and defines the exact selection criteria: missing, empty, or still identical to the primary locale. The returned shape { key: primaryValue } and the phrase 'one call returns exactly what needs translating, nothing else' implicitly distinguish it from broader siblings like get_translations.

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?

Explicitly names the intended caller ('the preferred way for a per-locale translation agent to fetch its own work') and describes the follow-up workflow with a named sibling: after writing a slice with add_multiple_translations, call again. It also states the doNotTranslate exclusion condition, so the agent knows when keys will not appear.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read-only lookup and 'across all locales' hints at the result shape, but there is no statement about authorization/prerequisites, whether a missing key errors or returns empty, or performance characteristics. Adequate for a low-risk getter, but thinner than the no-annotation bar ideally demands.

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, both earning their place: the first states the purpose and scope, the second handles routing to the alternative. The scoping and usage guidance are front-loaded 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?

There is no output schema, and while the description conveys that results span all locales, it doesn't describe the exact return shape (e.g., locale-to-string map) or behavior on a missing key. For a simple read-only lookup this is close to complete, with only minor gaps.

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 description coverage is 100%, so both parameters (key, namespace) are already documented with format hints in the schema. The description adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline of 3 applies.

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 names a specific verb and resource ('Get the translations') and defines the scope precisely: 'a single key across all locales.' It also distinguishes itself from the sibling get_translations, which returns the whole namespace, so an agent can choose between them without opening either 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?

It states the selecting condition ('targeted lookups', 'inline spot-checks') and names the concrete alternative (get_translations) along with why it is unsuitable ('too large'). That is explicit when-to-use and when-not-to-use guidance tied to a specific sibling.

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

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

No annotations are provided so the description carries the full burden, and it delivers: it discloses the size cap, the truncated-slice-plus-note failure mode, and the correct recovery action rather than a retry. This is behavioral context well beyond what any schema could convey.

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?

Four sentences, each earning its place, front-loaded with return shape and purpose before filters and the truncation caveat. No padding.

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?

Covers purpose, filter semantics, the duplicate-check workflow, and the truncation-failure recovery. With no output schema, the description still states the return structure, leaving nothing an agent needs to call it correctly missing.

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 baseline is 3, but the description adds real meaning the schema lacks: glob applies to keys ('button.*') while substring applies to any locale value, and it clarifies the query's role as a truncation-avoidance lever.

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?

Specific verb+resource ('get all translations for a namespace') with the exact return shape stated. Distinguishes itself from siblings by naming get_namespace_keys and get_translation as narrower alternatives.

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?

States an explicit when-to-use rule ('Always call this before adding new keys to check for duplicates') and a when-not/recovery path ('narrow the query instead of retrying — or use get_namespace_keys and get_translation').

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