Skip to main content
Glama
keivanmalhani

shutter-mcp

by keivanmalhani
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

blur_scores

Read-onlyIdempotent

Scores JPG files in a directory for blur using Laplacian variance, flags the blurriest bottom decile as likely_blurry, and returns results sorted from blurriest to sharpest.

Instructions

Score jpg files under a directory for blur using Laplacian variance.

jpg/jpeg only in the MVP. Lower variance means less high-frequency detail, i.e. more likely blurry. Results are sorted ascending (blurriest first); the bottom decile is flagged likely_blurry.

Args: params (BlurScoresInput): Validated input containing: - root (str): Directory of jpg files to score, must be inside an allowed --root - limit (int): Max files to score, default 500, 1-5000

Returns: dict: { "schema_version": 1, "root": str, "files_considered": int, "files_scored": int, "sampled": bool, "sample_note": str | None, "skipped": int, "results": [ {"path": str, "laplacian_variance": float, "likely_blurry": bool}, ... ], # sorted ascending by laplacian_variance } On error: {"schema_version": 1, "error": str}

Examples: - Use when: "Which jpgs in this folder are probably out of focus?" - Don't use when: the library has RAW files only (RAW pixel decode is out of scope for MVP)

Input Schema

NameRequiredDescriptionDefault
paramsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already cover readOnly/idempotent/non-destructive, so the description is free to add value elsewhere — and it does: results sorted ascending, bottom decile flagged likely_blurry, sampling when the file count exceeds limit, and the error envelope. It stops short of saying how the flag threshold is computed or whether the walk is recursive, which leaves a little ambiguity about scope of the directory traversal.

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 core sentence, then method, then args/returns/examples in a predictable structure. The Args section largely restates the schema and the Returns block is long, but since no output schema exists the return dump earns its place.

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?

Given two parameters, no output schema, and read-only annotations, the description supplies everything else an agent needs: return keys including sampled/sample_note/skipped, sort order, the likely_blurry semantics, and the error shape. Nothing material is left for the caller to guess.

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

Parameters4/5

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

Schema coverage is reported at 0%, so the description must compensate, and it does: it explains that root must live inside an allowed --root and that limit defaults to 500 with a 1–5000 range. It doesn't explain what 'allowed --root' concretely means or how the containment check fails, which is the one gap.

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 (score), resource (jpg files under a directory) and the method (Laplacian variance), which nothing in the sibling list (scan_library, library_stats, read_exif, find_duplicates, cull_report) duplicates. It also scopes the MVP to jpg/jpeg only, so an agent knows immediately this is the blur-quality pass rather than a general library scan.

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?

The Examples block gives an explicit 'Use when' trigger (which jpgs in this folder are probably out of focus?) and an explicit 'Don't use when' exclusion (RAW-only library, since RAW decode is out of MVP scope). That is precisely the when/when-not guidance an agent needs to route between this and scan_library or read_exif.

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