pictor-mcp

Crop an image

image_crop

Crop images by pixel box, aspect ratio with gravity anchor, or auto-trim uniform borders to remove unwanted areas and adjust composition.

Instructions

Crop by explicit pixel box, by aspect ratio with a gravity anchor, or auto-trim a uniform border.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`box`	No	Explicit (left, top, right, bottom) box in pixels.
`url`	No	http(s) URL to fetch. Disabled unless PICTOR_ALLOW_NET_FETCH=true.
`path`	No	Path to the image, relative to an allowed input root (or absolute inside one).
`trim`	No	Auto-remove a uniform border instead of using box/aspect_ratio.
`clamp`	No	Clip a box that falls outside the image instead of failing.
`gravity`	No	Which part to keep: center, top, bottom-left, ...	center
`quality`	No	Lossy quality 1-100 (higher is better quality and larger).
`base64_data`	No	Inline image bytes as base64, optionally a data: URI.
`output_name`	No	Override the output filename (a safe name is derived if omitted).
`aspect_ratio`	No	Crop to this width/height ratio, e.g. 1.0 for square, 1.7778 for 16:9.
`return_image`	No	Embed the resulting image inline so vision-capable clients can see it.
`output_format`	No	Output codec: jpeg, png, webp, avif, tiff, gif, bmp, ico, jpeg2000, qoi, ppm. Defaults to the input format.
`return_base64`	No	Include the base64 payload in the JSON result for clients without file access.
`strip_metadata`	No	Remove EXIF/GPS/ICC metadata. Defaults to the server setting (on).
`trim_tolerance`	No	Colour tolerance for trimming.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	No
`input`	No	Summary of the source image, when one was read.
`notes`	No
`steps`	No
`metrics`	No	Operation-specific measurements (e.g. comparison scores).
`outputs`	No
`operation`	Yes	Tool that produced this result.
`sizeChange`	No
`inlineImageIncluded`	No	True when an image block accompanies this result for vision-capable clients.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 15, 2026

TDQS

A3.9/5.0

Behavior3/5

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

With no annotations, the description carries the disclosure burden. It does explain the core behavior (three crop strategies and gravity anchoring), but it does not mention side effects, input-source requirements, non-destructiveness, or output behavior. These are not contradictory, but are left to the schema/output schema.

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

Conciseness5/5

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

A single, well-structured sentence that leads with the action and enumerates the three modes in order. Every word contributes; no filler.

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

Completeness3/5

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

Given 15 optional parameters, the description is terse: it does not state what happens if multiple crop modes are supplied together (box, aspect_ratio, trim), nor clarify input-source selection. However, the rich per-parameter schema and output schema cover most necessary details.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline applies: the description only groups the parameters into conceptual modes and adds no new syntax or semantic detail beyond what the parameter descriptions already contain.

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 description identifies the action (crop) and resource (an image) and names three distinct operation modes: pixel box, aspect-ratio with gravity, and uniform-border trim. This makes it readily distinguishable from sibling operations like image_resize or image_rotate.

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

Usage Guidelines4/5

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

The description implicitly tells the agent when to use each mode (precision box, aspect-ratio composition, or auto border trim) but does not explicitly state when not to use the tool or name alternatives. Since context is clear and no exclusions are needed, this is slightly above minimum.

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

Deploy Server