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

With no annotations, the description carries the full burden of disclosing behavior, and it delivers by specifying the contents of the return value (config, directory listings, active mode) and the exact semantics of the 'provider'/'agent' mode condition. It does not explicitly state read-only nature or side-effect absence, but for a discovery tool this is a minor omission given the thorough output specification.

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 front-loaded with the main purpose, then expands into precise details about return values and layerGraph. Each sentence adds unique information with no redundancy or filler, making it highly navigable for an agent.

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 is complete for a zero-required-param discovery tool: it explains what is returned, the formatting of active mode, the meaning of layerGraph, and when to use it. No output schema exists, but the text fully compensates by describing all key return categories.

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 only parameter, projectDir, has 100% schema description coverage including its default behavior. The tool description does not add anything beyond this, but the schema already fully explains the parameter, so the baseline score 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 uses a specific verb ('Discover') and resource ('i18n setup'), then enumerates exactly what is returned: project config, per-layer directory listings, and active translation mode. It clearly differentiates this from siblings by positioning it as the initial project-holding tool rather than one of the specific translation operations.

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 gives explicit when-to-use guidance: 'Call this first to understand the project before reading or writing translations.' It also explains when layerGraph is relevant (for deciding where a new key belongs), providing clear context without explicitly listing negative cases or alternative tools.

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 disclosure burden. It is upfront about reporting one locale at a time, emitting both values and a divergent flag, and explaining the runtime shadowing danger. The read-only nature is made clear through 'compares' and 'reports', and the 'never by moving' caution adds important behavioral context beyond the schema.

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 three tight, purposeful sentences. It leads with the core operation, quickly gives a concrete monorepo example, then explains the runtime danger and the safe fix. Every sentence adds distinct value and no space is wasted.

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 tool with five parameters, no annotations, and no output schema, the description gives a strong behavioral outline: it identifies collision semantics, output flag, locale behavior, and recommended resolution. It does not spell out projectDir defaults or exact output structure, but the input schema covers those, and the description's orientation is enough for an agent to use the tool confidently.

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 input schema covers all 5 parameters with full descriptions, providing the baseline. The description only adds minor contextual semantics, such as the single-reference-locale behavior, but does not restate or deepen parameter meanings meaningfully. Given 100% schema coverage, this is adequate and does not need heavy compensating explanation.

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 opens with a precise verb-resource pair, 'find translation keys', and specifies the exact scope: keys present in BOTH a shared layer and a consuming app layer. The runtime shadowing explanation further clarifies why these collisions matter, distinguishing this from sibling find_* tools that look at empty, missing, orphan, or undefined keys.

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 clearly identifies when to use this tool: whenever a key exists in both the shared and app layers and you want to detect shadowed values. It does not explicitly name sibling tools as alternatives or state when not to use them, but the 'BOTH shared layer and app layer' framing and the 'fix by deleting one side' guidance provide solid usage context.

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 must carry the burden. It discloses that empty strings are present in the locale file and 'render as nothing in the UI', which is useful behavioral nuance. It doesn't specify the return format or whether the output is a list, but the read-only nature is implied by 'find' and the behavior described is sufficient for basic decisions.

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: purpose, rationale, and usage guidance. Each sentence contributes new information with no redundancy or filler, making the description efficient and well-structured.

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 establishes the empty-string nuance and provides a concrete trigger scenario, which is essential for distinguishing from missing-translation tools. It doesn't mention output details or pagination, but the outputFile parameter hints at large outputs, and the description seems adequate for a read-only find tool given the schema's richness.

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 input schema already provides detailed descriptions for all four parameters (layer, locale, outputFile, projectDir), so the description adds no additional parameter semantics. Baseline of 3 applies because schema coverage is 100%.

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 uses a specific verb ('Find') and resource ('keys whose value is an empty string'), and clarifies how this differs from missing translations, distinguishing it from sibling tools like get_missing_translations and find_undefined_keys.

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 states when to use ('after a scaffold or an interrupted translation run') and explains the context (keys that were created but never filled). It doesn't list alternatives or exclusions, but the context is clear enough for an agent to choose this tool.

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 provided, the description carries the full behavioral burden and does substantial work: it discloses dynamic key detection, uncertain matches, scope-aware per-layer checking, and the misplacedUsages distinction. It stops short of specifying the complete result format or explicitly confirming non-mutating behavior, but 'reports' and 'can potentially be removed' imply read-only intent.

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 dense but well organized: core definition first, then layer behavior, then edge-case handling. Every sentence earns its place, and the scope-related caveats justify the length.

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 complex tool with no output schema and no annotations, the description covers the key outcomes: potential removals, dynamic/uncertain matches, scanScope summary, and misplacedUsages. It could more fully enumerate the returned data structure, but it provides enough context for correct selection and 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?

The input schema already documents all 6 parameters with detailed descriptions, so the baseline is 3. The description adds useful context about layer scope and consuming apps, but it does not materially enhance per-parameter understanding 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 opens with a specific verb and resource: 'Find translation keys that exist in locale JSON files but are not referenced in any Vue/TS source code.' It clearly defines the tool's scope and distinguishes it from sibling tools like find_undefined_keys and find_duplicate_keys.

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 clearly conveys when to use this tool—to identify potentially removable translation keys—and describes scope-aware scanning with misplacedUsages separated from orphans. It does not explicitly name alternative tools for related use cases, but the intended context is unambiguous.

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 takes on the full burden and discloses the key limitation that extraction is line-based and static, reporting dynamically built keys as uncertainKeys rather than hard findings. This is critical behavioral transparency. It also explains scope awareness, but does not explicitly state whether the operation is read-only or has any side effects beyond writing to an optional outputFile.

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 concise and well-structured: it states the purpose, explains the scope, and then highlights the known limitation, all in a few sentences. It front-loads the key differentiator (inverse of find_orphan_keys) and ends with a relevant limitation. Every sentence adds value without 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?

The description covers the tool's purpose, scope, and a major limitation, which is substantial given no output schema. It does not explicitly describe the return format (e.g., list of keys, uncertainKeys vs hard findings), though the outputFile parameter mentions a compact summary. Given the complexity (5 params, no annotations), the description is fairly complete but could be improved by explicitly stating what the tool returns in terms of hard findings and uncertainKeys.

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 input schema already provides 100% coverage with clear descriptions for each parameter, so the baseline is 3. The tool description adds minimal extra semantics about parameters; it mentions scope-aware scanning and the scanDirs override, but this is already stated in the schema. It does not elaborate on the interaction between parameters beyond what the schema covers.

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 clearly states it finds keys referenced in source but not defined in any consumed locale file, positioning it as the inverse of find_orphan_keys. It uses specific verbs ('find', 'referenced', 'defined') and distinguishes from siblings by explicitly describing its scope-aware behavior and the 'raw keys to production' scenario.

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 provides strong contextual cues by labeling itself as the inverse of find_orphan_keys and explaining the production risk scenario, which implies when it should be used. However, it does not explicitly enumerate alternative tools or state clear 'when not to use' conditions beyond the static-analysis limitation.

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 of disclosing behavior. It merely states the action without mentioning side effects (e.g., whether it is read-only), performance implications, or output structure beyond a vague 'compact summary' only mentioned in a parameter description. The description itself does not tell the agent if this is a safe operation or if it might produce large responses.

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 two tight sentences, each carrying meaningful information. It front-loads the core purpose and adds the layer-scanning nuance without fluff. Every word earns its place, making it highly concise and well-structured.

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?

Given the tool has 5 parameters, no annotations, and no output schema, the description is too sparse. It does not explain the return format (compact vs. full output), how layer scanning interacts with the output, or the relationship between referenceLocale and targetLocales. The presence of siblings with nuanced differences makes the description incomplete for safe invocation without further inference.

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 input schema has 100% description coverage, so the baseline is 3. The description adds minimal parameter value: it mentions 'reference locale' and 'other locales' conceptually, which aligns with referenceLocale and targetLocales, but does not provide extra semantic depth beyond what the schema already states. Since the schema fully documents all parameters, the description does not need to compensate heavily.

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 clearly states the tool's function: 'Find translation keys that exist in the reference locale but are missing in other locales.' It also adds the layer-scoping detail ('Scans a specific layer or all layers'), which distinguishes it from related tools like find_orphan_keys (different basis) and find_empty_translations (different condition). This specificity makes the purpose unambiguous.

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?

No explicit guidance on when to use this tool versus alternatives. The description only explains what it does, not when it should be preferred over sibling tools like find_orphan_keys or get_translation_status, nor any prerequisites such as requiring a valid reference locale. The parameter descriptions hint at defaults but do not provide contextual use cases or 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The verb 'Get' implies a non-destructive read operation, but the description never explicitly confirms read-only behavior, response format, pagination, or other operational traits. The wildcard note about reading all locales is the only behavioral detail beyond the obvious, which is thin given zero annotation coverage.

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 wasted words. The first sentence states the core purpose and the second adds the single most useful operational tip. Front-loaded and efficient.

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 schema is rich (100% parameter coverage) and this is a straightforward getter, so the minimal description is mostly adequate. However, with no annotations and no output schema, the description could clarify the response shape or explicitly confirm there are no side effects. It's functional but doesn't compensate for what structured fields don't cover.

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 the baseline of 3 applies. The description's wildcard note ('Use "*" as locale to read from all locales') is already captured in the schema's locale parameter description, so the description adds no new parameter semantics beyond the structured fields. 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?

The description uses a specific verb ('Get') with a specific resource ('translation values for given key paths from a specific locale and layer'). It clearly communicates this is a read operation for specific keys, which distinguishes it from sibling write tools like write_translations. However, it doesn't explicitly differentiate from closest siblings like get_missing_translations or search_translations, leaving some differentiation implicit.

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 usage context: 'for given key paths' suggests this is the right tool when you have specific keys in mind rather than broad searches. The explicit tip about using '*' as locale provides practical operational guidance but relates to parameter usage rather than tool-selection guidance versus alternatives.

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?

The description explains key behaviors: handling of empty strings, exclusion of protected locales, and that it returns only a summary. However, it does not explicitly state whether the tool is read-only or if writing to outputFile is a side effect, leaving some ambiguity.

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 concise, using three sentences that each add essential information without redundancy. It is well-structured and easy to parse.

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 provides sufficient context for a user to understand what the tool does, its output, and special conditions. It explains the summary return and the handling of protected locales and empty strings, making it complete for a read-only reporting tool.

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?

All four parameters are thoroughly described in the JSON schema, covering layer, outputFile, projectDir, and referenceLocale. The description adds no new information beyond the schema, so it meets the baseline for parameter clarity.

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 clearly states the tool's purpose: computing translation coverage statistics with per-locale and per-layer counts, plus an overall percentage. It distinguishes itself from sibling tools like get_missing_translations by offering a consolidated view.

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 explicitly recommends using this tool instead of calling get_missing_translations per layer, and explains edge cases (empty strings count as untranslated, protected locales excluded from overall). This provides clear when-to-use guidance.

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 provided, the description carries the full burden. It discloses the return format ('hierarchical view... counts per namespace node'), which is useful, and 'List'/'explore' imply read-only behavior. However, it doesn't state side-effect safety explicitly, performance implications for large trees, or error conditions.

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, all earning their place: the action, the output shape, and the usage context. Front-loaded with the verb+resource, no filler or repetition of schema content.

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 read-style exploration tool with 3 optional params and no output schema, the description covers purpose, return shape, and usage context adequately. It partially compensates for the missing output schema by describing the hierarchical view with counts. A brief explicit read-only/safety note would make it fully complete given zero annotations.

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 the baseline of 3 applies. The schema already documents defaults, examples, and meanings for layer, locale, and projectDir. The description adds no parameter-specific detail beyond the general 'namespace prefix' context, so it neither elevates nor degrades the baseline.

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 uses a specific verb+resource ('List the translation key tree grouped by namespace prefix') and clarifies the output shape ('hierarchical view of all keys with counts per namespace node'). It's clearly distinct from siblings like search_translations or get_translations by its grouping/exploration framing, though it doesn't explicitly name 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?

'Use this to explore available keys without guessing path prefixes' provides an explicit use case, but there are no when-not-to-use conditions or named alternatives among the 16 sibling tools. The guidance is present but implied rather than comparative.

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 behavioral burden and discloses the critical behavior: it writes nothing if the target layer holds a different value, deduplicates locales when the value matches, supports dryRun for preview, and carries every locale. It would be complete with a little more detail about dryRun output shape, but the main side effects are clear.

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 dense but well-organized: it states the operation, adds the motivating scenarios, gives a prerequisite, then covers side-effect semantics and dryRun. Every sentence earns its place and there is 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?

For a mapping tool with no annotations and no output schema, the description covers purpose, prerequisites, main behavior, conflict semantics, deduplication, and dryRun preview. The only modest gap is the exact shape of the dryRun plan, which is not output by described beyond 'preview'.

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 the schema already documents every parameter. The description adds useful behavioral context around key movement and dryRun, but it does not need to explain each parameter further, leaving it at the baseline.

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 operation: moving a translation key between layers while carrying every locale that defines it. It also grounds the purpose in concrete use cases, promoting an app-layer key to a shared layer and demoting a shared key that became app-specific, which removes ambiguity.

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 explicitly says to call discover first and points the agent to layerGraph.shared as the source of layer choices. It also frames when the move is appropriate, and the schema's toLayer description directs renames within a single layer to rename_translation_key.

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 burden. It discloses the critical safety behavior: 'Always does a dry run first' and that keys referenced only from non-consuming apps are 'reported as misplacedUsages and never removed.' This provides concrete behavioral expectations beyond basic removal. However, it does not mention potential side effects like irreversibility when dryRun=false, or any permission requirements, which would be valuable for a destructive tool. Still, the dry-run disclosure and placement logic add substantial transparency, so a 4 is warranted.

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 two sentences, both dense with information. The first sentence states the core action; the second adds scope-aware behavior and the misplacedUsages rule. No fluff, no redundancy. Front-loaded with the verb and resource, it's an exemplary model of conciseness.

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?

Given the tool's complexity (7 params, destructive action, no output schema, and no annotations), the description provides a solid overview: what it does, the dry-run default, and scope handling. It covers the critical behaviors, but it could be more complete by mentioning the default when layer is omitted (though schema does) or explaining the return value summary vs outputFile. Since the schema fills some gaps and the description mentions the outputFile parameter's purpose implicitly, it's adequate but not exhaustive. The lack of a return-value description is a minor gap, so a 4 is appropriate.

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 baseline is 3. The description adds extra meaning by explaining the scope-aware logic tied to layer and scanDirs (e.g., 'each layer is checked against its consuming apps' and how misplacedUsages are never removed). This goes beyond the schema's parameter descriptions, enriching the agent's understanding of how layer and scanDirs affect behavior. The dry-run default is already in schema, but the description reinforces it by saying 'Always does a dry run first,' which is a behavioral nuance.

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 clearly states the action: 'find orphan keys (not referenced in source code) and remove them from all locale files.' It distinguishes from sibling 'find_orphan_keys' by including removal, and from 'remove_translations' by specificity to orphans. The phrase 'Scope-aware like find_orphan_keys' references a sibling but also clarifies the tool's scope behavior, making the purpose unambiguous.

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 gives clear context on when to use this tool—when you need to remove orphan keys—and mentions the dry-run first behavior, implying a safe workflow. It references scope-aware behavior similar to find_orphan_keys, giving context on how it interacts with layers. However, it does not explicitly state alternatives (e.g., 'use find_orphan_keys to search only') or when not to use it, such as when you only want to find orphans without removal. The lack of explicit exclusions prevents a 5.

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. It discloses the destructive scope (removing from ALL locale files) and the dryRun preview, which is useful. However, it does not mention reversibility, required permissions, or return format, leaving meaningful gaps.

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 two sentences, front-loaded with purpose, and every word adds value. It includes the essential dryRun guidance without any fluff.

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 covers purpose and the key safety feature, but with no output schema and no annotations, it lacks details about return values, behavior for missing keys, and side effects on files. For a mutation tool affecting multiple files, this is a moderate gap.

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 the schema already documents all parameters with examples. The description only reinforces the layer and dryRun concepts without adding new semantic details, matching the baseline.

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 clearly specifies the verb 'Remove' and the resource 'translation keys from ALL locale files in the specified layer', which distinguishes it from sibling tools like remove_orphan_keys and rename_translation_key. The scope is explicit and unambiguous.

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 clearly states when to use the tool (to remove translation keys) and highlights the dryRun option as a safety measure. However, it does not explicitly contrast with alternatives or mention when not to use it, so it lacks explicit 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?

No annotations are provided, so the description carries the full burden. It discloses that the operation preserves values in every locale, which is a key behavioral trait. It also mentions dryRun for previewing without writing files, which is important for safety. However, it does not mention potential side effects like overwriting existing keys (though the schema says newKey must not exist) or whether the operation is reversible. Still, the description adds meaningful behavioral context beyond the schema.

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 two sentences, front-loaded with the core purpose, and includes a practical tip about dryRun. Every word earns its place; no fluff or repetition.

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?

Given the tool's complexity (5 params, no output schema, no annotations), the description covers the essential purpose, scope, and safety preview. It doesn't explain return values, but since there's no output schema, that's a minor gap. The description is sufficient for an agent to understand the tool's function and when to use it.

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 schema description coverage is 100%, so the schema already documents all parameters well. The description adds minimal extra meaning beyond the schema, but it does reinforce the scope ('ALL locale files') and the dryRun behavior. Since the schema is comprehensive, a baseline of 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?

The description clearly states the tool's purpose: 'Rename/move a translation key across ALL locale files in a layer.' It specifies the verb (rename/move), the resource (translation key), and the scope (all locale files in a layer). It also distinguishes from siblings by emphasizing the cross-locale scope, which is unique among the listed tools.

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 provides clear context on when to use the tool: when renaming a key across all locale files. It also mentions the dryRun option to preview changes, which is a usage hint. However, it does not explicitly state when NOT to use it or mention alternatives (e.g., for single-file renames), but the context is clear enough for an agent to decide.

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 provided, the description carries the full burden. It discloses that values are set to empty strings, that JSON and PHP formats are supported, and that it does not modify the framework config. It does not mention what happens if files already exist or what the return value is, which prevents a perfect score.

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?

Every sentence earns its place: the main action, the key-structure behavior, supported formats, and the all-important config caveat are all front-loaded and concise. No filler 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 write/scaffold tool with 4 params and no output schema, the description is reasonably complete. It explains the behavior, the data format, and the critical prerequisite about config. The only notable gap is that it does not describe what the tool returns (e.g., created file paths or summary) for non-dry-run calls.

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 the schema already documents all 4 parameters. The description does not add new parameter-level semantics, but it provides useful background about locale structure and formats, which slightly supports understanding. 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?

The description opens with a specific verb and object ('Create empty locale files for new languages') and explains the exact behavior: copying the default locale's key structure with empty values. This clearly distinguishes it from sibling tools like write_translations, get_translations, or translate_missing.

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 explicitly states when to use it (new languages needing scaffolded files) and provides the key prerequisite warning that the agent must add the locale to the config first. It also explicitly prescribes 'Does NOT modify framework config.' It does not name alternative tools, but the usage context is clear.

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 behavioral burden. It discloses the matching semantics (simple case-insensitive substring, not fuzzy/regex), which is helpful, but it does not explicitly state that the operation is read-only, describe the result format, or mention behavior with large result sets. These gaps reduce transparency.

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 concise with three short sentences, front-loading the action and then efficiently adding the key limitation and use case. It contains no redundant phrases or buzzwords.

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 is adequate for a search-only tool but leaves some gaps. There is no output schema, and the description does not explain what the tool returns beyond the mention of a 'compact summary' in the outputFile parameter, which is not part of the main description. The behavior for empty results, multiple matches, or very large result sets isn't clarified.

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 input schema provides detailed descriptions for all six parameters with 100% coverage, so the baseline is met. The description does not add parameter-level meaning beyond mentioning key path or value, which is already captured by the query and searchIn parameter descriptions.

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 clearly states that the tool searches translation files by key path or value, with a specific verb and resource. It also explicitly characterizes the match type as simple case-insensitive substring, which distinguishes it from fuzzy or regex-based searches and from sibling tools like get_translations or write_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?

The description says it is 'useful for finding existing translations before adding duplicates,' which gives a clear when-to-use context. It also clarifies the limitation (not fuzzy/regex) but does not recommend an alternative tool for those or other cases, so it stops short of providing explicit exclusions or alternatives.

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?

Beyond the readOnlyHint:false annotation, the description discloses that the operation can overwrite existing stale translations, how provider mode writes directly, and that agent mode returns a fallbackContext requiring separate persistence. These are important behavioral side effects not present in the annotation or schema.

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, information-dense, and immediately front-loads the core action and key differentiator. It avoids repeating schema details and every clause contributes meaningful guidance about behavior, modes, or alternatives.

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 nine-parameter tool with no output schema, the description covers the operation, the key edge behavior (overwrite), mode differences, and the follow-up write path. It gives an agent enough contextual grounding to select the tool and know important side effects before invoking it.

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 the baseline is 3. The description adds operational context around one or two parameters (e.g., overwrite behavior, source value handling), but most parameter meaning is already fully captured by the input schema, so it does not substantially exceed baseline.

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 clearly states the tool adds or updates a source translation key and translates it into target locales. It also distinguishes itself from translate_missing by explicitly noting that it can overwrite existing stale target translations, which separates it from its closest sibling.

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 explicitly references translate_missing as the alternative and clarifies when translate_key is preferable (overwriting stale translations). It also explains the two operating modes and directs the agent to persist agent-mode results via write_translations, giving actionable usage guidance.

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?

Annotations only specify readOnlyHint: false, which is minimal. The description discloses all relevant side effects and behaviors: writes results in provider mode, requires persisting via write_translations in agent mode, uses project config (glossary, prompt, notes, examples), translates all locales concurrently, and supports dryRun to avoid side effects. It also explains that the server calls the LLM provider directly, which is a key behavioral trait. This is far more transparent than the annotations alone and leaves no ambiguity about mutations.

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 a dense, well-structured paragraph that fronts the core action and then efficiently covers modes, defaults, concurrency, and output variations. Every sentence adds distinct value without redundancy or fluff. Despite its length, it remains concise for the complexity of the tool, and the information is organized logically from function to modes to configuration to output.

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?

Given 8 parameters, no required ones, and no output schema, the description carries the full burden of explaining behavior. It covers all essential aspects: mode determination, configuration dependencies, side effects, concurrency, output shapes (e.g., per-locale fallbackContexts, compact summary fields), and the recommended usage for layer. It also mentions the project config influence. This is comprehensive and leaves no significant gaps for an agent to misuse the tool.

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 schema already provides 100% coverage with descriptive parameter definitions. The description adds significant value on top: it clarifies the default behavior for keys (all missing keys), for layer (every locale-backed layer, recommended default), and for dryRun (returns which keys would be translated without calling LLM or writing). It also adds the nuance that batchSize is provider-mode-only and explains the output formats for compact mode. This enriches the schema's meaning with usage context that the agent needs for correct invocation.

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 clearly states the tool's core function: 'Find keys missing in target locales and translate them.' It distinguishes itself from siblings like get_missing_translations (which only finds) and translate_key (which handles a single key) by combining both actions and supporting batch/whole-layer processing. The verb 'translate' with resource 'missing keys' is specific and unambiguous.

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 explicitly explains when to use each mode: provider mode (when I18N_PROVIDER, I18N_MODEL, and API key are configured) versus agent mode (otherwise). It instructs to 'Check the discover output for the active mode' and provides workflow guidance for agent mode: 'translate those inline and persist via write_translations.' It also advises on the recommended default for layered projects and emphasizes passing all targetLocales at once for concurrency. This goes beyond generic context and gives actionable, mode-specific usage instructions.

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 mode behaviors (skip existing/missing keys), default upsert, alphabetical key insertion, and dryRun's no-write preview. It does not explicitly mention file mutation effects or permissions, but the core behavioral traits are surfaced.

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?

Description is three purposeful sentences: purpose, mode/behavior, and usage note. Front-loaded, no fluff, 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?

The complexity is moderate (5 params, nested object, no output schema), and the description covers the essential write semantics, mode differences, insertion order, and dryRun. Could add a note on whether existing layer files are merged or overwritten for transparency, but overall adequately contextual.

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% with thorough descriptions for all 5 parameters, so the bar for the description is low. The description adds a few extras (alphabetical order, dryRun preview, default mode context) but these are marginal and largely restate or slightly expand what the schema already offers.

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 uses a specific verb ('write') with a clear resource ('translation key-value pairs to a layer') and enumerates three modes that expand the scope. It clearly distinguishes itself from siblings by covering the primary bulk-write operation, unlike read, remove, rename, or translate tools.

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 gives explicit when-to-use guidance for each mode (upsert/add/update), calls out the default most common mode, and recommends dryRun for preview. However, it does not explicitly contrast with sibling tools like translate_missing or get_translations, so alternative exclusion is absent.

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