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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds that output volume can be controlled via checks, but says nothing about result grouping, performance on large projects, or how the four finding types are structured in the response.

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 tight sentences with zero filler: the scope ('Project-wide health check') is front-loaded, the four findings follow, and the closing scoping tip ends the description. Every clause carries information.

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-only audit with no output schema, the description adequately conveys what kinds of findings are returned and how to limit them via `checks` and `limit`. It stops short of describing the shape or grouping of the returned findings, which an agent may still need to plan around, but nothing critical for invoking it correctly is 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 the baseline is 3, but the description genuinely expands semantics beyond the schema: it explains what 'missing' means (keys absent in some locale relative to the base locale), what 'code' means (used in code but untranslated), and what 'unused' means (never referenced in code) — none of which the bare enum list conveys. The baseLocale relationship is also clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('Project-wide health check') and enumerates the exact four findings it produces: missing keys vs base locale, placeholder mismatches, code-used-but-untranslated keys, and unused keys. This enumeration maps directly onto the `checks` enum values and clearly separates the tool from read-oriented siblings like i18n_search_keys or i18n_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?

The closing sentence 'Choose checks to keep the response small' is a usage hint for scoping the response, and the 'vs the base locale' phrasing implies the comparison context. However, it never says when to reach for this tool versus siblings (e.g. i18n_search_keys or i18n_key_references) or when not to run it, leaving the choice largely to inference.

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 already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, but they do not convey the crucial default-preview behavior. The description supplies exactly that (preview unless dryRun:false or dialog confirmation), which is real value beyond structured fields. It omits recovery/undo and non-existent-key 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?

Two tight sentences with the destructive-action caveat front-loaded immediately after the purpose. Every clause earns its place and nothing is padded.

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 destructive, four-parameter tool with no output schema, the description covers the safety mechanism an agent most needs to avoid accidental data loss. Missing only edge-case behavior (missing keys, reversibility), which is minor given the annotation set.

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 75% and the schema already documents dryRun ('Default true (preview). false deletes.') and locales, so the description's 'dryRun:false' and 'all or selected locales' largely restate structured fields rather than adding syntax or format detail. No meaning is added for keys or workspaceDir.

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 (remove) plus resource (keys) and scope (all or selected locales), which cleanly distinguishes it from siblings like i18n_rename_key and i18n_upsert_translations. It stops short of explicitly naming an alternative to route against, so not a 5.

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 clear operational guidance: the call previews by default, and deletion requires dryRun:false or confirming the dialog. It does not, however, say when to prefer this over rename_key or upsert_translations, leaving sibling routing unaddressed.

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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully sketches the result shape (keys plus locales missing each), which substitutes for the absent output schema, but says nothing about performance on large workspaces or handling of files with no keys.

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 with zero filler; the result semantics come first and the workflow trigger follows. Nothing repeats the title or the 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?

For a read-only query tool with fully documented parameters, the description covers what the tool returns and when to run it, which is enough for correct invocation. The missing piece is disambiguation from i18n_key_references and the other i18n inspection siblings.

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 (filePath, workspaceDir, includeComplete) are already documented in the schema. The description adds no parameter-level detail beyond that, so the 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+resource: translation keys referenced in one source file, plus which locales lack them. The scope (one file) is clear, but it does not distinguish itself from the similarly named sibling i18n_key_references, which an agent could easily confuse with this tool.

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?

"Run after editing a component to verify its copy is complete" gives a concrete trigger condition. However, it names no alternatives (e.g. i18n_key_references, i18n_audit, i18n_search_keys) or when-not-to-use conditions, so routing among siblings still requires inference.

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 already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond that: preview-by-default semantics and the scope nuance that mixed files only get top-level key sorting. It stops short of describing what the preview output looks like, but that is a minor gap given the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly packed sentences with no filler; the operation comes first and the safe-by-default behavior is stated immediately after. Every clause carries information.

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 4-parameter, zero-required mutation tool with no output schema, the description covers the essential decision points (default preview, explicit opt-in to write, key sorting scope). It leaves unstated whether files must exist and what the preview reports, but nothing critical to correct invocation is 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 the baseline is 3; the dryRun explanation largely restates the schema description. The description nonetheless adds a semantic the schema lacks: sorting is limited to top level for mixed files, which clarifies the sortKeys parameter's real scope.

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 specific verbs and effect: 'Normalize JSON formatting and sort keys', which clearly identifies a formatting/rewriting tool for locale resources. It does not name or contrast with any sibling tool, but the purpose is unambiguous and distinct from the search/translation 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?

The description gives clear guidance on the dryRun default ('Previews by default; pass dryRun:false to rewrite'), which tells the agent how to actually apply changes. However, it offers no when-to-use-vs-alternative guidance and no mention of preconditions or when formatting is appropriate relative to i18n_audit or i18n_upsert_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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: 'null marks a missing translation' explains the return semantics for absent values, and the trailing-dot namespace rule describes an expansion behavior not evident from the name alone.

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 compact clauses with zero filler; the core scope ('values of specific keys in every locale') is front-loaded, followed by the two highest-value edge-case behaviors. 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 carries the burden of describing returns, and it does so partially by defining null as a missing translation. It does not clarify the overall response shape (per-key vs per-locale grouping) or how limit/maxValueChars shape the result, leaving a small gap for a six-parameter 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?

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all six parameters. The description still adds meaning beyond the schema by explaining that a '.'-suffixed key returns the whole namespace and that null signals a missing translation, which clarifies the effect of the keys and includeValues parameters at runtime.

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 (get values of specific keys across locales) and clarifies scope with '(or selected) locale'. It distinguishes exact-key lookup from the broader sibling tools like i18n_search_keys implicitly, 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?

Provides one conditional usage hint ('Use includeValues:false for presence only') which implies when the tool is useful for existence checks. However, there is no guidance on when to prefer this over i18n_search_keys or i18n_file_keys, and no exclusions or prerequisites are stated.

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 already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by stating the return format and that it provides exact totals, though it does not explain truncation behavior from the limit parameter.

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 short sentences, front-loaded with the core output shape and followed by the practical usage condition. 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 simple read-only lookup tool with full annotations and no output schema, the description supplies enough context: what it returns and when to use it. It could be slightly stronger by clarifying the effect of the limit parameter on the reported totals.

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 67%, with limit and workspaceDir already described in the schema. The description adds no parameter-level meaning beyond the schema, so it remains at the baseline adequate level.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb-resource relation: it finds where keys are used in code, and it adds the output shape (path:line:column) and exact totals. This clearly distinguishes it from lookup siblings like i18n_search_keys, though it does not explicitly name alternative 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?

It gives a clear usage context: 'Useful before renaming or deleting a key.' That tells an agent when the tool is valuable, but it does not name exclusions or alternative sibling tools for related tasks.

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 already establish read-only, idempotent, closed-world behavior, so the bar is lower. The description adds real workflow context: it must be called once per session before other tools, and it surfaces warnings and resolved config, which are non-obvious behavioral outputs.

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 short clauses with zero filler, and the highest-value instruction (call once per session before other tools) is placed at the end of a tight sentence pair. Every phrase carries information.

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 must convey return content, and it does by enumerating locales, key format, counts, config and warnings. It is complete enough to call correctly, though it could say more about how the resolved config/warnings should influence subsequent 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 coverage is 100% and the single workspaceDir parameter is documented there as 'usually omitted'. The description adds nothing about the parameter, 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 enumerates exactly what the tool surfaces — locales, key format, key counts, resolved config, warnings — which makes it distinguishable from the sibling key/translation CRUD tools. It lacks an explicit verb (e.g. 'returns'/'reports'), so it reads as an output list rather than a stated action, keeping it short of a 5.

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 directive 'Call once per session before other tools' gives explicit sequencing guidance that no sibling provides. It stops short of a 5 because it names no alternatives or when-not conditions, though the 'once per session' framing implies the info is cached/global.

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 already flag destructiveHint=true and idempotentHint=false, so safety framing is partly covered. The description adds genuinely new behavioral facts: preview-by-default (a non-obvious dry-run default), the hard refusal when a target key exists, and the namespace-vs-key branching rule. It still omits what happens to keys missing in some locales and any partial-failure 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 core operation, then the precondition, then the apply instruction. Every sentence carries distinct information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, multi-locale mutation with no output schema, the description covers the critical unknowns: default preview, refusal semantics, and mode selection. It is nearly complete, though it leaves open whether the operation is atomic across locales and what a preview returns.

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 80%, so the baseline is 3, but the description adds real meaning to 'from' (namespace prefix ending in '.') and 'dryRun' (default preview vs. apply) beyond the schema text. 'to' and locale behavior remain slightly underspecified in the 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 (rename) and resource (key), and adds a distinct second mode (whole-namespace move) with a concrete trigger ('from' ending in '.'). The example 'nav.' -> 'menu.' makes the operation unambiguous and separable from sibling mutation tools like i18n_upsert_translations or i18n_delete_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?

Explains the two modes and their selecting condition, plus a precondition (refuses when the target exists) and the apply path (dryRun:false). It does not explicitly compare against sibling tools, so it falls short of full when-to-use-vs-alternative guidance, but the operating 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond them: incomplete keys are flagged with the 'in' marker, and values are hidden unless includeValues is set. Return-shape specifics like ordering or pagination are still absent.

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 search semantics before the optional refinements. Every sentence carries information; no filler or restated boilerplate.

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, read-only search tool with no output schema, the description covers the search mode, prefix narrowing, the 'in' incompleteness marker, and value inclusion. It is complete enough to call correctly, with only minor gaps around result ordering and default locale behavior that the schema largely covers.

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 78%, so the schema already documents most of the nine parameters (limit, query, locales, searchIn, keyPrefix, includeValues). The description reinforces query/keyPrefix/includeValues and the default case-insensitivity but adds little syntax or format detail beyond the schema, making the baseline 3 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 and resource ('Find keys by substring of the key or the translated text') plus scope ('optionally under a key prefix'). An agent can distinguish it from i18n_file_keys or i18n_get_translations, though no sibling is named explicitly, so it stops short of a 5.

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 explains how to widen output ('Add includeValues to see the text') but never says when to reach for this tool versus i18n_get_translations, i18n_file_keys, or i18n_key_references. No prerequisites, exclusions, or alternative routing are given.

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 already declare write/idempotent/non-destructive, and the description adds genuinely new behavioral context on top: it writes immediately, never deletes keys, treats differing existing values as conflicts unless overwrite:true, and surfaces missing locales and placeholder mismatches. That is exactly the kind of consequence detail an agent needs before mutating translations.

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 short sentences, each carrying distinct information (scope, write/delete behavior, conflict rule, validation reporting), with the write-immediately and never-deletes facts front-loaded. 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?

With no output schema, the description does describe what gets reported back (missing locales, placeholder mismatches), which covers the key return signal. Minor gaps remain around dryRun behavior and the exact shape of the conflict report, but nothing essential for correct invocation is 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 75% and the schema already documents dryRun, overwrite, key format and the values map. The description adds meaning beyond the schema's terse overwrite text by explaining that a differing value is a conflict unless overwrite:true, clarifying the practical effect of the flag rather than restating it.

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 (create/update) and resource (translation keys), plus the per-locale value model, so an agent can tell it apart from i18n_delete_keys and i18n_rename_key by the explicit 'never deletes keys' framing. It stops short of naming a sibling alternative directly, so it is clear but not maximally differentiated.

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?

Usage is implied rather than stated: create or update keys in one call. The overwrite:true condition is spelled out, which helps routing within the tool, but there is no explicit when-to-use-this-vs-i18n_rename_key or i18n_get_translations guidance and no stated prerequisites.

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