Remove Orphan Keys

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.