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

Annotations already declare a safe, idempotent, read-only, closed-world operation, so the safety profile is covered. The description adds non-obvious behavioral detail the annotations lack: the 25-result cap, the 1,000 default scan and 2,000 hard ceiling. It does not explain truncation semantics or ordering, keeping it from a 5.

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

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

Three sentences, zero filler: the usage trigger is front-loaded, the output shape follows, and the exclusion closes it out. 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 tool is a simple, read-only two-parameter query. Although an output schema exists and return values need not be explained, the description still usefully summarizes the return shape (repeated values plus the keys sharing them). Nothing needed to call 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 both parameters are already documented, including scanLimit's range and 1000 default. The description restates the same default and ceiling rather than adding syntax or meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('finding keys that repeat the same default-language text') and the goal (clean up a project). This clearly distinguishes it from sibling diagnostics like find_missing_translations even without naming them.

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 a concrete when-to-use trigger ('when someone wants to clean up a project by finding keys that repeat...') and an explicit exclusion ('Not for untranslated strings') that routes the agent toward find_missing_translations. It stops short of naming that alternative sibling directly, so it is not a full 5.

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