check_duplicates

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 near=True is a placeholder (not functional), which is critical to avoid misuse. It also explains the behavior with keys (duplicate groups) and gives output size. It does not mention permissions or read-only nature, but 'check' implies read-only; still, the placeholder disclosure adds significant value.

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 short sentences, front-loaded with the core purpose. Every sentence adds value: the first states the exact detection scope, the second explains behavior with keys, and the third clarifies the near placeholder and output size. No redundant or filler 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?

Given the tool's simplicity (3 params, output schema present), the description covers the essential behavior: what it detects, parameter effects, and output size. It doesn't mention prerequisites like having a loaded source, but that's implied by source_id. It also doesn't mention return format, but the output schema covers that. Slightly incomplete regarding edge cases or error conditions, but otherwise solid.

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 only lists parameter names with no descriptions (0% coverage). The description compensates by explaining 'keys' (duplicate groups under those keys) and 'near' (placeholder for Phase 3 fuzzy matching). This adds meaning beyond the schema, particularly for near, which could otherwise be misinterpreted as functional fuzzy matching.

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 'Exact duplicate detection (Level 2)' which clearly specifies the tool's purpose and scope. It further distinguishes from fuzzy matching by noting near=True is a placeholder, making it clear that this tool is for exact duplicates only. This separates it from sibling tools like clean_drop_duplicates or check_quality.

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 for exact duplicate detection, especially when fuzzy matching is not yet available (near=True is a placeholder). However, it does not explicitly state when to use this tool over alternatives like clean_drop_duplicates or check_quality, nor does it mention any exclusions. The 'Output size: small' hint is useful but not a full guideline.

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