optiq-mcp

Overview Schema Source Related Servers Discussions Admin

Optimize images

optimize_images

DestructiveIdempotent

Optimizes images and writes the results in place or to an output folder, replacing files only when quality checks pass and the new file is smaller.

Instructions

Optimises images and writes the results. If the user only wants to know how much could be saved, or has not agreed to changes yet, use analyze_images instead: it takes the same arguments and writes nothing. write: "in-place" overwrites each file and keeps its format and name, so references in code stay valid (atomic rename). write: "out-dir" writes to outDir, mirroring the folder structure, and may change formats; extensions change accordingly, so update references. A file is only replaced when the result passes the quality check and is smaller. Files Optiq already compressed lossily are skipped (unless reoptimize is true), so calling this twice is safe. Choosing parameters: mode visually-lossless for hero images, artwork and product photos, lossless for logos and UI assets that must stay exact, balanced otherwise; stripMetadata before publishing personal photos (GPS); formats without avif if old browsers matter. Takes the same time as analyze_images (typically 0.3-3 s per image).

Input Schema

Name	Required	Description	Default
`mode`	No	How strict the quality check is. lossless: decoded pixels verified identical (JPEG inputs only get metadata changes). visually-lossless: SSIM >= 0.99. balanced (default): SSIM >= 0.975. fast: same threshold as balanced, no AVIF, at most 5 encodes, about 3x faster. Use visually-lossless for hero images, artwork and product photos.	balanced
`paths`	Yes	Image files and/or folders. Folders are searched recursively for jpg, jpeg, png, webp, avif and gif; dot-folders are skipped. Use absolute paths; relative ones resolve against the server's working directory.
`write`	Yes	"in-place" overwrites inputs; "out-dir" writes to outDir.
`outDir`	No	Required when write is "out-dir".
`formats`	No	Formats Optiq may choose when the format may change. Default: all four (fast mode: no avif). Drop avif if the site must support browsers older than Safari 16.4. JPEG is never chosen for images with transparency.
`maxSize`	No	Downscale so the longest side is at most this many pixels, e.g. 2560 for camera photos on a website. Smaller images are not enlarged. Allowed in lossless mode too (the resize itself changes pixels).
`minSaving`	No	Keep a file unchanged unless it gets at least this share smaller (0.05 = 5%). Default 0.02. Raise it to avoid churning files for tiny gains.
`keepFormat`	No	Never change the file format (a .png stays PNG). Default: true for in-place writes and for analysis, false when writing to outDir. Set false in analysis to see what converting to WebP/AVIF would save.
`minQuality`	No	Custom SSIM threshold for perceptual modes instead of the mode's default, e.g. 0.98. Higher keeps more detail and saves less. Ignored in lossless mode.
`reoptimize`	No	Re-encode files Optiq already compressed lossily. Each lossy pass loses a little more quality; leave false unless the user asks.
`stripMetadata`	No	Remove EXIF (including GPS location, camera serial) and XMP. Recommended before publishing personal photos. Colour profiles that matter (non-sRGB ICC) and image orientation are preserved either way.

Output Schema

Name	Required	Description
`files`	Yes
`dryRun`	Yes
`totals`	Yes
`omittedFiles`	Yes	Files processed but not listed (the list is capped); totals include them.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.1.2Oct 29, 2026

changedInput schema / properties / formats / description

Previous value: -"Formats allowed when the format may change. Default all four. Drop avif if the site must support old browsers."New value: +"Formats Optiq may choose when the format may change. Default: all four (fast mode: no avif). Drop avif if the site must support browsers older than Safari 16.4. JPEG is never chosen for images with transparency."

changedInput schema / properties / keepFormat / description

Previous value: -"Never change the file format. Default: true for in-place writes and analysis, false when writing to outDir."New value: +"Never change the file format (a .png stays PNG). Default: true for in-place writes and for analysis, false when writing to outDir. Set false in analysis to see what converting to WebP/AVIF would save."

changedInput schema / properties / maxSize / description

Previous value: -"Downscale so the longest side is at most this many pixels."New value: +"Downscale so the longest side is at most this many pixels, e.g. 2560 for camera photos on a website. Smaller images are not enlarged. Allowed in lossless mode too (the resize itself changes pixels)."

changedInput schema / properties / minQuality / description

Previous value: -"Custom SSIM threshold for perceptual modes, e.g. 0.98."New value: +"Custom SSIM threshold for perceptual modes instead of the mode's default, e.g. 0.98. Higher keeps more detail and saves less. Ignored in lossless mode."

changedInput schema / properties / minSaving / description

Previous value: -"Keep a file unchanged unless it gets at least this much smaller. Default 0.02."New value: +"Keep a file unchanged unless it gets at least this share smaller (0.05 = 5%). Default 0.02. Raise it to avoid churning files for tiny gains."

changedInput schema / properties / mode / description

Previous value: -"lossless: pixels verified identical. visually-lossless: SSIM >= 0.99. balanced (default): SSIM >= 0.975. fast: like balanced, no AVIF, fewer encodes. Use visually-lossless for hero images, artwork, product photos."New value: +"How strict the quality check is. lossless: decoded pixels verified identical (JPEG inputs only get metadata changes). visually-lossless: SSIM >= 0.99. balanced (default): SSIM >= 0.975. fast: same threshold as balanced, no AVIF, at most 5 encodes, about 3x faster. Use visually-lossless for hero images, artwork and product photos."

changedInput schema / properties / paths / description

Previous value: -"Image files and/or folders (searched recursively, dot-folders skipped). Absolute paths recommended."New value: +"Image files and/or folders. Folders are searched recursively for jpg, jpeg, png, webp, avif and gif; dot-folders are skipped. Use absolute paths; relative ones resolve against the server's working directory."

changedInput schema / properties / stripMetadata / description

Previous value: -"Remove EXIF (including GPS location) and XMP. Recommended before publishing photos."New value: +"Remove EXIF (including GPS location, camera serial) and XMP. Recommended before publishing personal photos. Colour profiles that matter (non-sRGB ICC) and image orientation are preserved either way."

First observedOct 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations flag destructiveHint=true and idempotentHint=true, but the description supplies the costly context behind them: in-place is an atomic rename preserving format and name so code references stay valid, out-dir mirrors folder structure but changes extensions so references must be updated. It also discloses the safety gate (a file is replaced only if it passes the quality check and is smaller), the skip of previously lossily-compressed files, and the runtime cost.

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 purpose and the sibling alternative before the detail, and the sentence-per-idea structure is dense but readable. A few clauses duplicate what the parameter descriptions already say verbatim in spirit (mode for hero images, avif for old browsers), so it is slightly longer than necessary.

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?

An output schema exists, so return values need not be explained; the description instead covers the mutation semantics, safety gate, idempotency, skip behavior, and timing that an agent needs to call an 11-parameter destructive write tool responsibly. Nothing material is missing.

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 already 100%, so the baseline is 3; the description still adds real meaning the schema does not carry, notably the reference-invalidation consequence of outDir format changes and the guidance that stripMetadata matters for GPS/personal photos. It also restates some schema content (mode thresholds, avif browser support), so it is additive rather than fully compensating.

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?

The opening sentence names a specific verb and resource ("Optimises images and writes the results") and immediately contrasts the scope with the sibling tool analyze_images, which "writes nothing." An agent can distinguish the two 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?

Explicitly states when to use the sibling instead ("If the user only wants to know how much could be saved, or has not agreed to changes yet"), then gives parameter-selection rules of thumb: visually-lossless for hero images/artwork, lossless for logos and UI assets, stripMetadata before publishing personal photos, drop avif for old browsers. Both the tool choice and the argument choice are covered.

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

Deploy Server