Find values that are written down in more than one place

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

Annotations already signal read-only, idempotent, and closed-world behavior. The description adds value beyond these by explaining a key nuance: a second copy is treated as a second value even if it has not yet disagreed with the original. It also discloses how patterns work (presets vs. regex) and that anything outside presets becomes a regular expression. This extra context about interpretation and pattern handling goes beyond what annotations provide.

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 well-structured with a clear lead sentence, an illustrative rationale, and parameter guidance. It is slightly verbose, but each sentence contributes value—explaining the tool's purpose, the reasoning behind it, and the behavior of key parameters. It front-loads the core function before diving into nuances, making it easy to scan.

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 six parameters, the description covers the essential behavioral aspects: what it does, how it handles duplicates, how to restrict to a single source, default patterns, and the regex fallback. Since an output schema exists, the absence of return-format details is acceptable. Nothing critical is missing for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all parameters have basic descriptions. The description adds meaningful nuance: it enumerates the preset pattern names, explains that non-preset strings are regular expressions, and clarifies the intended use of source_of_truth (the one file allowed to hold values). This goes beyond the schema's terse descriptions, enriching the semantics for pattern-related and source_of_truth parameters.

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 scans for values appearing in more than one file and reports them. The verb 'Scans' and 'reports' are specific, and the resource (values that are repeated across files) is well-defined. It even sets itself apart from sibling check tools (copy, honesty, assets) by focusing on duplication across files, making its 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 provides implicit usage guidance: it explains when to enforce the strict form via source_of_truth, and gives a real-world example to illustrate the problem it solves. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions. The context is clear enough for an agent to infer its primary use case, but not explicit about alternatives.

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