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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, and the description goes further: it discloses the composite execution path (which four tools run under the hood), that the output is markdown text only, that it never writes a file, and that failures surface as 'Error: <message>'. That is exactly the added context the annotation baseline doesn't cover.

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 core purpose and the composed-tool list are front-loaded, and the when/when-not pair is efficient. The Args/Returns sections are mild boilerplate that restate the schema, but they cost little and the failure-mode line 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?

An output schema exists, so return shape needs no prose, yet the description still names the report sections (library summary, top EXIF stats, duplicate groups, blurriest 20 jpgs) and the error contract. For a single-parameter, side-effect-free aggregation tool, an agent has everything needed to call 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?

One parameter, and the description's 'root: Directory to report on, must be inside an allowed --root' largely mirrors the schema's own text ('must resolve inside an allowed --root'). It reinforces the sandbox constraint but adds no syntax, path-format, or resolution detail beyond the schema.

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 artifact ('build a markdown cull report') and enumerates exactly which inputs it combines (scan, EXIF stats, dupes, blur). It also names the sibling tools it orchestrates, so an agent can immediately tell it apart from scan_library, library_stats, find_duplicates, and blur_scores, which produce the component data.

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 Examples block gives an explicit when-to-use ('summary I can read before I start culling this shoot') and an explicit when-not ('you need machine-readable output — use the individual tools instead'), naming the alternative. Nothing about selection is left to inference.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds important behavioral context beyond those annotations: it documents sampling by newest modification time when sample_limit is exceeded, counts skipped files with no readable EXIF, enforces that root must be inside an allowed --root, and specifies the error return shape.

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 front-loaded with purpose and scanning behavior, then uses structured Args, Returns, and Examples sections. Despite its length, every section adds actionable information, and the return schema detail is warranted because no output schema is present.

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 has no output schema, but the description provides a detailed return structure, including counts, sampling indicators, and error shape. Combined with explicit parameter documentation and usage examples, it gives an agent everything needed to invoke the tool 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 reported as 0%, so the description carries the full burden for parameter semantics. Its Args section fully documents both nested parameters: root as an allowed-root-constrained directory and sample_limit as a bounded max-file count with default 2000 and 1-50000 range, including the newest-mtime sampling behavior.

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 states a specific verb and resource: aggregate EXIF metadata across a library for cameras, lenses, ISO, focal length, and dates. It clearly distinguishes this from per-file EXIF access by explicitly directing users to read_exif for that need.

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 Examples section gives explicit when-to-use cases and a when-not-to-use case that names the sibling alternative read_exif. This leaves little ambiguity about when library_stats is the right choice.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavior the annotations cannot: best-effort support across a named format list, the crucial non-error degradation path (empty fields plus a note for missing EXIF or unsupported extensions), and the --root sandbox constraint on path. It even documents the error return shape, so failure modes are predictable.

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?

Front-loaded with purpose and graceful-degradation behavior, which is the right ordering. The Args block largely restates the schema and the Returns block is verbose, but since no output schema exists, enumerating the field keys earns its space.

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?

With no output schema and only one input parameter, the description carries the return contract and does so fully: schema_version, path, present-only field keys, GPS as floats, the optional note, and the distinct error envelope. Nothing an agent needs in order to call this correctly or interpret the result 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 description coverage is reported at 0% (the wrapper `params` object carries no description), so the description must compensate, and it does: it explains that `path` points to exactly one image file and must resolve inside an allowed --root. The nested schema property already says nearly the same thing, so the added value is real but partly duplicative.

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 ("Read flattened EXIF fields") and bounds the scope to "a single image file," which separates it from the aggregate sibling library_stats. An agent can pick this over the other five siblings without opening any schema.

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?

Provides an explicit "Use when" phrasing ("What lens and settings were used for this specific frame?") and an explicit "Don't use when" that names the alternative (library_stats) for cross-file aggregates. The routing decision is fully specified rather than inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, but the description still adds real substance: symlinks are not followed, the walk halts at 50000 files, truncation is reported in the result, and errors return a schema_version/error dict. That is exactly the kind of behavior an agent cannot infer from structured fields.

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?

Front-loaded with a one-line summary, then behavior, then args/returns/examples in a scannable order. It is somewhat long, but with no output schema the Returns block earns its space; the redundancy of mentioning library_stats twice is the only real waste.

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?

With no output schema and 0% schema description coverage, the description carries the full burden and does so: it documents every returned key including the truncation fields and the error shape. An agent can call this correctly and interpret the result without further information.

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?

There is only one parameter and the description restates its constraint (must be inside an allowed --root), which is the operative safety boundary for the call. The schema's own field description already carries this, so the description adds reinforcement rather than new meaning; a 4 rather than a 5 for a single trivially-shaped string param.

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 first sentence gives a specific verb and resource ("Recursively scan a directory and summarize"), and the body adds scope boundaries: walks recursively, does not follow symlinks, does not read contents or EXIF. It explicitly names the sibling for the EXIF case, so it is distinguishable from library_stats 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.

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

The Examples block states both when to use ("How many files are in my 2026 shoot folder and how big is it?") and when not to use, naming library_stats as the alternative for EXIF aggregates. The body also routes to library_stats a second time, reinforcing the exclusion.

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