Skip to main content
Glama
keivanmalhani

shutter-mcp

by keivanmalhani
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

find_duplicates

Read-onlyIdempotent

Detect exact duplicate files or visually similar JPG/PNG images in a directory to identify redundant copies for cleanup or review.

Instructions

Find duplicate files under a directory, exact or visually similar.

'exact' mode groups byte-identical files (any file type) by sha256 hash. 'visual' mode groups jpg/png images whose perceptual hash (phash) is within a hamming distance of 5, catching near-duplicate bursts even when bytes differ. Visual mode internally samples up to 3000 newest files for performance on very large libraries. Returns at most 200 duplicate groups; truncated indicates whether more groups exist beyond that cap.

Args: params (FindDuplicatesInput): Validated input containing: - root (str): Directory to scan, must be inside an allowed --root - mode ("exact" | "visual"): Duplicate detection mode, default "exact"

Returns: dict: { "schema_version": 1, "root": str, "mode": str, "files_considered": int, "duplicate_group_count": int, "truncated": bool, "groups": [{"count": int, "files": [str, ...]}, ...], # visual mode additionally includes: files_hashed, sampled, sample_note, truncation_note # exact mode additionally includes: skipped, total_duplicate_groups_found } On error: {"schema_version": 1, "error": str}

Examples: - Use when: "Find exact duplicate files I can safely delete one copy of." - Use when: "Find near-duplicate frames from burst shooting." - Don't use when: you want blur ranking, not duplication (use blur_scores)

Input Schema

NameRequiredDescriptionDefault
paramsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the description focuses on what annotations cannot express: the 3000-file sampling cap in visual mode, the hamming-distance threshold, and the 200-group output cap with a 'truncated' flag. These are exactly the performance and truncation caveats an agent needs before trusting results on a large library.

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

Conciseness4/5

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

Front-loaded with the core statement and mode semantics, then structured Args/Returns/Examples blocks. The Args section largely restates the input schema, which is redundant, but the Returns documentation earns its space since no output schema exists.

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

Completeness5/5

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

No output schema exists, and the description fully specifies the return shape including mode-specific extra fields (files_hashed/sampled vs. skipped/total_duplicate_groups_found) and the error envelope. Nothing an agent needs to interpret a response or call correctly is missing.

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

Parameters5/5

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

With schema description coverage reported at 0%, the description carries the full burden and does: it explains root as a directory that must resolve inside an allowed --root, and mode's two values with their algorithms, defaults, and file-type scope (any type vs. jpg/png). This meaningfully exceeds the bare enum.

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

Purpose5/5

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

States a specific verb and resource ('Find duplicate files under a directory') and immediately names the two detection modes with their defining algorithms (sha256 byte-identity vs. phash hamming distance <= 5). It also explicitly distinguishes itself from the blur-ranking sibling by name, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides concrete 'Use when' scenarios (safe-to-delete exact copies, near-duplicate burst frames) and an explicit 'Don't use when' that names the alternative tool (blur_scores). When-to-use, when-not, and the alternative are all present.

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

Deploy Server

Other Tools