Imagor MCP is a template layer on top of imagor that lets an agent compose, validate, render, and verify image transformations as a single signed imagor URL.
Build signed imagor URLs from typed transformation parameters (resize, crop, fit modes, flips, filters), with composition validated before the URL is returned.
Describe the imagor path grammar, signing mode, signer type, truncation, and limitations this server targets.
List imagor filters with signatures, descriptions, and accepted argument forms, generated from imagor's own reference.
Read the imagor skill covering path order, overlay/text placement, resize modes, and silent-failure gotchas.
Fetch ready-made cookbook recipes (canvases, slots, values) to start from instead of composing from scratch.
Render multi-slot layouts (text, image, rect, nested canvases) at any canvas size, with placeholders, relative geometry, fitted text, and per-slot filters.
Parse an existing imagor path back into an editable template, and validate paths for round-trip stability and problems.
Find the largest font size that fits a text box via fit_text, so titles don't overflow.
Verify a composition against a running imagor: fetch results, report per-filter outcomes (applied/declined/not reported), dimensions, and an optional preview image or region at native resolution.
Check server compatibility, nested-path support, and filter-reporting capability.
An MCP server and a skill that add a template layer to imagor.
An agent writes a layout: OG cards, product grids, quotes, testimonials. It compiles to one imagor URL, rendered by the imagor you already run.
1. Run an imagor.
docker run --rm -p 8000:8000 shumc/imagor -imagor-unsafeLeave it running, and use a second terminal for the rest.
Unsafe mode is for trying things out. Production runs on IMAGOR_SECRET. See
imagor's security docs.
2. Install the MCP server.
brew trust cshum/tap && brew install imagor-mcp3. Point a client at it.
your client | what to do |
VS Code | add it from here — one click |
Claude Desktop | open |
Cursor, Claude Code, Windsurf | add the block below to its config file |
Codex | the same values in TOML, at |
{
"mcpServers": {
"imagor": {
"command": "imagor-mcp",
"env": { "IMAGOR_UNSAFE": "1", "IMAGOR_BASE_URL": "http://localhost:8000" }
}
}
}Those two settings have to match what you started in step 1: IMAGOR_UNSAFE puts this server
in the same mode, and IMAGOR_BASE_URL is where imagor is.
VS Code keys its servers under servers and Codex reads TOML, so the block above fits
neither. Every client's config file is in Setup.
4. Ask it for something. See the recipes — each one carries a prompt to paste, or describe the image you want. The agent composes through the tools: it writes the layout, renders it, looks at the result, and hands you back the url. Neither of you needs imagor's path syntax: the tools build the path, and refuse one that cannot work.
That is the whole install. It is also in the official MCP Registry as
io.github.cshum/imagor-mcp, which some clients install by name, and as
ghcr.io/cshum/imagor-mcp in a container, which needs a different base
URL, in Setup. Windows binaries are on the
releases page.
Before anything is public, read Security: what this server is trusted with, and what it refuses.
Related MCP server: Media Toolkit MCP Server
Setup — every setting, the config file each client reads, and what to do before it is public.
Reference — every tool the server serves, the layout format, and the skill.
Cookbook — the ready-made layouts, and the url each one resolves to.
Contributing — building, testing, and the CLI.
MIT
Build a signed imagor image URL from typed transformation parameters. Requires IMAGOR_SECRET to be configured. The composition is validated before the URL is returned, so an invalid combination is refused rather than emitted. Read get_imagor_skill before composing anything, and call list_imagor_filters for each filter's signature, description and accepted argument forms, which are generated from imagor's own filter reference. Build and verify in a loop: a request returns 200 whether or not a filter did anything, so pass the same parameters to verify_imagor_url rather than assuming it worked. For a composed layout rendered at a canvas size, use render_template.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | return image metadata only, without processing the image | |
| trim | No | trim surrounding space using the top-left pixel colour | |
| image | Yes | the source to transform, not a composed result: a URL or path such as "example.com/a.jpg", or a synthetic source such as "color:red" or "color:none" | |
| smart | No | use content-aware smart crop | |
| width | No | target width in pixels; 0 means automatic | |
| fit_in | No | fit inside width x height instead of cropping to fill; the result can be smaller than the box on one side | |
| h_flip | No | mirror horizontally | |
| height | No | target height in pixels; 0 means automatic | |
| v_flip | No | mirror vertically | |
| filters | No | ordered filters, applied left to right. Arguments are validated against imagor's catalogue: call list_imagor_filters for a filter's signature, description and accepted argument forms. image() loads its argument as its own canvas, so positions inside it are relative to the overlay | |
| h_align | No | horizontal alignment, either "left" or "right" | |
| stretch | No | stretch to exactly width x height, ignoring aspect ratio, which distorts the image; use full_fit_in to fill a box of a different shape without distorting it | |
| trim_by | No | trim anchor, either "top-left" or "bottom-right" | |
| v_align | No | vertical alignment, either "top" or "bottom" | |
| crop_top | No | crop top edge: a fraction 0-1 of the height, or absolute pixels when greater than 1 | |
| crop_left | No | crop left edge: a fraction 0-1 of the width, or absolute pixels when greater than 1 | |
| crop_right | No | crop right edge: a fraction 0-1 of the width, or absolute pixels when greater than 1 | |
| crop_bottom | No | crop bottom edge: a fraction 0-1 of the height, or absolute pixels when greater than 1 | |
| full_fit_in | No | cover the box without cropping: one side matches width x height and the other exceeds it, keeping the aspect. Use for an image that must fill a panel without cutting into it. Requires fit_in, and add upscale() when the source is smaller than the box | |
| trim_tolerance | No | trim tolerance from 0 to 255 | |
| adaptive_fit_in | No | invert width and height when that yields better definition; requires fit_in | |
| max_age_seconds | No | add a max_age() filter limiting how long the response may be cached | |
| expire_unix_millis | No | add an expire() filter so the URL stops working after this unix-milliseconds timestamp |
| Name | Required | Description |
|---|---|---|
| url | No | a request path ready to send to imagor, including its signature or unsafe prefix |
| mode | Yes | how the path was produced: signed or unsafe |
| note | No | human-readable notes about the result |
| path | Yes | the imagor path, without any signature or unsafe prefix |
| signed | Yes | whether the URL carries a signature |
| warnings | No | compositions that are valid but will not do what was intended |
| absolute_url | No | the full URL to fetch, present only when IMAGOR_BASE_URL is configured |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does: it discloses the IMAGOR_SECRET prerequisite, that invalid compositions are refused rather than emitted, and the critical non-obvious trait that a 200 response does not prove a filter applied, so verification requires verify_imagor_url. It also flags silent failure modes (comma truncation, '?' altering the signed path, 403/404).
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 purpose and prerequisite, and every sentence is actionable rather than filler. It is dense and runs several guidance clauses together in one long paragraph, which slightly impedes scanning, but no sentence is wasted.
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 23 parameters, no annotations, and an output schema (so return shape need not be explained), the description supplies the missing pieces: auth requirement, validation behavior, verification loop, and sibling routing. An agent has everything needed to call it correctly and to check its work.
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 100%, so the baseline is 3, but the description adds parameter-level meaning the schema does not: composition is validated against imagor's catalogue before emission, and the same parameter set must be replayed through verify_imagor_url to confirm effect. The filter-argument guidance largely duplicates the schema's own notes, which caps it below 5.
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 ('Build a signed imagor image URL from typed transformation parameters'), including the signing constraint that distinguishes it from a plain URL builder. It explicitly routes away from siblings: get_imagor_skill, list_imagor_filters, verify_imagor_url, and render_template for composed layouts. An agent can place it in the toolset 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?
Gives explicit sequencing (read get_imagor_skill before composing, call list_imagor_filters per filter), an alternative for a different job ('For a composed layout rendered at a canvas size, use render_template'), and the exact condition that selects the alternative. Nothing about when-to-use 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.
Describe the imagor path grammar this server targets, including the parameters reflected from imagor's own path type and the current signing mode.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| mode | Yes | signed or unsafe |
| base_url | No | |
| truncate | Yes | signature length in characters; must match IMAGOR_SIGNER_TRUNCATE on that imagor |
| setup_note | Yes | what has to agree between this server and the imagor it points at, and what a disagreement looks like |
| limitations | Yes | |
| path_params | Yes | path grammar parameters, reflected from the imagor path type |
| signer_type | Yes | signature algorithm; must match IMAGOR_SIGNER_TYPE on the imagor this server points at |
| filter_count | Yes | number of filters accepted by the tools |
| h_align_values | Yes | |
| imagor_version | Yes | the imagor release the filter catalogue was generated from |
| trim_by_values | Yes | |
| v_align_values | Yes | |
| signing_enabled | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the returned subject matter (grammar, reflected path-type parameters, current signing mode). However it never states that this is a read-only, side-effect-free lookup, nor anything about response format or cost, which matters for a zero-annotation tool.
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?
A single sentence that front-loads the core purpose ('Describe the imagor path grammar this server targets') before listing the included content. Slightly dense but every clause adds information; nothing is wasted.
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 values need not be described here, and with no inputs there is little else to specify. The description is complete enough for an informational tool, though it could note the read-only nature and when to prefer it over get_imagor_skill.
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?
The tool takes zero parameters, so the baseline is 4 and there is no parameter documentation burden. The mention of 'parameters reflected from imagor's own path type' refers to the tool's output, not inputs, so it adds no schema-relevant meaning.
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: it describes the imagor path grammar the server targets, and names the concrete content (path-type parameters, signing mode). It does not explicitly differentiate itself from siblings like get_imagor_skill or list_imagor_filters, but an agent can tell it is the grammar/config reference tool.
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?
Usage is implied by the tool's nature: call it when you need to know the path grammar or signing mode before building or validating paths. No explicit when-to-use, prerequisites, or named alternatives (e.g. vs get_imagor_skill) are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the largest font size at which a string still fits a box. imagor wraps text but never shrinks it, so a template that suits a short title silently overflows on a longer one. This renders the text on a transparent canvas at candidate sizes, measures the ink, and searches for the largest size that fits. Pass the returned font argument straight to text(). Requires IMAGOR_BASE_URL.
| Name | Required | Description | Default |
|---|---|---|---|
| font | Yes | a Pango font with hyphens for spaces, family first and size last, e.g. Open-Sans-bold or Liberation-Serif-24 | |
| text | Yes | the string to fit; it may contain %0A for a hard line break | |
| color | No | text colour; affects nothing measurable, and defaults to black | |
| max_size | Yes | largest size to try, in points | |
| min_size | No | smallest size to accept; the search stops here and reports that it does not fit | |
| box_width | Yes | width of the area the text has to fit, in pixels | |
| box_height | Yes | height of that area; the wrapped text may not exceed it |
| Name | Required | Description |
|---|---|---|
| fits | Yes | whether a size at or above min_size fits the box |
| font | Yes | the font argument to pass to text(), family and size together |
| note | No | |
| size | Yes | |
| lines | Yes | how many lines the text wrapped to at this size |
| width | Yes | measured ink width in pixels |
| height | Yes | measured ink height in pixels |
| probes | Yes | how many renders the search needed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does well: it discloses the mechanism (renders on a transparent canvas at candidate sizes, measures the ink, searches for the largest fit) and the hard prerequisite IMAGOR_BASE_URL. It does not mention cost, how many candidate sizes get rendered, or failure behavior at min_size beyond what the schema says.
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 outcome, then the motivation, mechanism, integration step, and prerequisite in four tight sentences with no filler. Every sentence earns its place; nothing is repeated from the schema.
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 need not be explained, and the description instead covers the parts structured data cannot: why the tool exists, how it works internally, the IMAGOR_BASE_URL prerequisite, and the hand-off to text(). For a 7-parameter tool this is complete enough to invoke 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 100%, so the schema already documents all seven parameters including the min/max search bounds and the Pango font format. The description adds only that the returned font value is what text() expects, which is output-side rather than parameter-side. Baseline 3 is correct.
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 outcome: 'Find the largest font size at which a string still fits a box,' plus the rationale that imagor wraps but never shrinks text. It is unmistakably a font-fitting search tool. It never names or contrasts a sibling, but no sibling (build_imagor_url, render_template, etc.) competes for this job, so differentiation is not the gap.
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?
Gives a clear trigger context (a template that suits a short title silently overflows on a longer one) and a downstream instruction: 'Pass the returned font argument straight to text().' It also states the prerequisite (IMAGOR_BASE_URL). It stops short of explicit when-not-to-use or cost/latency caveats for what is clearly an expensive search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a ready-made layout by name: canvas, slots and values, ready for render_template. Call it with no name first to get the list - what each layout is for, its size, and which values it takes - then call it again with the one you want. Prefer starting from a recipe over composing from nothing: they encode spacing and type sizes that took iteration to get right.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | a recipe name from the cookbook, for example event or og-standard. Leave it out to get the list of recipes, with what each is for and which values it takes. |
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| note | No | |
| index | No | |
| render | No | |
| template | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the dual-mode behavior (omitted name returns a catalog including purpose, size, and expected values) and the read-only nature implied by 'fetch'. It stops short of covering failure behavior for an unknown name or any auth/rate considerations, which is a minor gap for a read-only getter.
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?
Three sentences, front-loaded with what the tool returns, then the invocation pattern, then the rationale. Every sentence earns its place with no redundancy.
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-value detail is not required from the description; it still summarizes the payload usefully. The one-parameter surface and its two modes are fully covered, leaving only edge behavior (invalid recipe name) unaddressed.
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 100% and the schema description already documents the single 'name' parameter, including the omit-to-list behavior and examples like 'event' or 'og-standard'. The prose largely restates that, adding only pipeline framing rather than new parameter semantics, so baseline 3 is appropriate.
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 (fetch) and resource (ready-made layout/recipe) and describes the payload it returns (canvas, slots, values). It also ties itself to the pipeline by saying the result is 'ready for render_template', distinguishing it from siblings like parse_template and render_template.
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?
Explicitly prescribes the two-call workflow ('call it with no name first' to enumerate, then again with the chosen name) and gives a clear preference rule ('prefer starting from a recipe over composing from nothing') with the reason (encoded spacing/type sizes). Nothing 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.
Read this before composing anything. The order a path is written in, how overlays and text are placed, what the resize modes actually do, and the things a 200 response will not tell you. Called with no section it returns the outline; call again with a section name to read the part you need.
| Name | Required | Description | Default |
|---|---|---|---|
| section | No | a section name from the list this tool returns when it is omitted; omit it to get the list |
| Name | Required | Description |
|---|---|---|
| note | No | |
| skill | Yes | the skill text returned: the outline when no section was named, or that section |
| section | No | the section that was returned, when one was named |
| sections | Yes | every section name, so a caller can ask for a different one without another call |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does disclose the non-obvious calling pattern: no argument yields an outline, a named argument yields the body. It also flags that it covers caveats a 200 response hides, which is genuinely useful context. It does not explicitly state the read-only nature of the call, though that is trivially inferable for a documentation reader.
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?
Three tight sentences, front-loaded with the imperative and the motivating topics, then the mechanics of the argument. No filler and nothing important buried.
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 values need no explanation, and the description covers the workflow, the covered topics, and the caveat angle. It does not hint at what sections exist or how granular they are, but the dynamic outline design makes that acceptable.
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 100% and the schema already states that omitting section returns the section list, so the description's 'call again with a section name' largely restates it. The added nuance is the iterative two-pass workflow, which the schema only implies. Baseline 3 is appropriate since the schema does the heavy lifting.
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 communicates that this is a reference/skill document to be read before composing imagor paths, and enumerates the topics it covers (path order, overlay and text placement, resize modes). The verb+resource is implied rather than stated, and it never differentiates itself from the sibling describe_imagor, which an agent could easily confuse it with.
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?
It gives a clear directive on when to consult it ('Read this before composing anything') and explains the two-step retrieval pattern (omit section for the outline, then fetch the section you need). It stops short of naming alternatives or when-not-to-use cases such as validate_imagor_path or describe_imagor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the imagor filters this server accepts, with each filter's signature, description and accepted argument forms, generated from imagor's own filter reference. imagor ignores unrecognised filters and wrong argument counts silently — the request returns 200 with the image unchanged — so use this to pick filters that exist instead of guessing names.
| Name | Required | Description | Default |
|---|---|---|---|
| name_contains | No | optional case-insensitive substring to filter names by, for example "strip" to find the metadata filters |
| Name | Required | Description |
|---|---|---|
| note | No | |
| count | Yes | |
| filters | Yes | |
| imagor_version | Yes | the imagor release the catalogue was generated from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does disclose a non-obvious trait: unrecognised filters and wrong argument counts are ignored silently, returning 200 with the image unchanged. That is exactly the kind of gotcha an agent needs, though permissions/rate-limit context is absent (likely irrelevant here).
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?
Two sentences, no filler. The purpose and contents are front-loaded, and the operational warning follows compactly.
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 values need no further explanation, and the description already summarizes what each returned entry holds. Combined with the failure-mode warning and the optional filter param, an agent has everything needed to call this 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 coverage is 100% and the schema already documents name_contains with its own example ('strip' to find metadata filters). The description adds nothing further about the parameter, so the baseline 3 for high schema coverage applies.
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 (list) and resource (imagor filters this server accepts) and enumerates what each entry contains (signature, description, accepted argument forms). It is immediately distinguishable from siblings like build_imagor_url or validate_imagor_path.
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?
It gives a clear condition for use: pick filters that exist instead of guessing names, motivated by the silent-failure behavior. It does not explicitly name a sibling to use instead, but the trigger context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read an imagor path back into a template, so one you already have can be edited rather than retyped. This is the inverse of render_template and the two are meant to be used together: render, look, adjust the JSON, render again. Read get_imagor_skill before composing anything. Note that the geometry comes back absolute - a path records the numbers a template resolved to, not the forms it was written in. To check a path without converting it, use validate_imagor_path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | an imagor path, or a full URL, to read back into a template. The path is what render_template produces, so a path you already have can be turned into something you can edit. |
| Name | Required | Description |
|---|---|---|
| note | No | |
| slots | Yes | |
| values | No | |
| background | Yes | |
| canvas_width | Yes | |
| canvas_height | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the key behavioral trait that geometry is returned as absolute numbers rather than the written forms, which an agent would otherwise get wrong. It doesn't state output shape, but an output schema exists, so this is the one remaining gap.
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-loads the core purpose, then workflow, then prerequisite, then the subtle absolute-geometry caveat, then the alternative. Four sentences, each earning its place with no filler.
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?
Covers purpose, workflow pairing with render_template, prerequisite skill, the non-obvious absolute-geometry behavior, and the sibling alternative. With an output schema handling return values and full schema coverage on the parameter, nothing an agent needs 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 100%, so the single 'path' parameter is already documented in the schema. The description adds only that it accepts a full URL and is what render_template produces, which overlaps with the schema text, so baseline 3 applies.
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 ('read back'/'parse') and resource (imagor path -> template), and explicitly distinguishes itself as the inverse of render_template. An agent can tell it apart from validate_imagor_path and render_template 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?
Explicitly describes the render/look/adjust/render workflow with render_template, names get_imagor_skill as a prerequisite, and routes to validate_imagor_path for path-checking-without-conversion. When-to-use and alternatives are both covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a layout at a given canvas size. Geometry is written the way imagor writes it, so slots can be positioned and sized relative to the canvas with full and full-N, and one template then serves several sizes. A text slot given a height is fitted with fit_text against the box its geometry resolves to, because a font size is absolute and would otherwise be relatively smaller on a larger canvas. Values fill {{placeholders}}. Returns the path, the URL, and what each slot resolved to. Verify it before handing it over - imagor answers 200 with the image unchanged when a filter does not apply, so a render that reports success is not a render that is right. For one image with typed parameters and no layout, use build_imagor_url.
| Name | Required | Description | Default |
|---|---|---|---|
| slots | Yes | the elements, applied in order, so later slots draw over earlier ones | |
| values | No | values for {{placeholders}} in slot text and image fields | |
| background | No | canvas background, for example color:1a1a2e; defaults to color:white | |
| canvas_width | Yes | canvas width in pixels | |
| canvas_height | Yes | canvas height in pixels |
| Name | Required | Description |
|---|---|---|
| url | No | |
| mode | Yes | |
| note | No | |
| path | Yes | |
| signed | Yes | |
| resolved | Yes | |
| absolute_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden, and it does real work: it discloses the return contents (path, URL, resolved slots) and a critical silent-failure mode ('imagor answers 200 with the image unchanged when a filter does not apply, so a render that reports success is not a render that is right'). It also explains the fitting behavior and placeholder substitution. Gaps: no permission/auth requirements and no other error semantics.
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 purpose, then geometry, fitting, placeholders, return, the verification warning, and the alternative in a sensible order; no filler sentences. The middle sentences are dense and somewhat convoluted ('fitted with fit_text against the box its geometry resolves to'), but each carries information an agent needs.
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?
For a complex tool with a deeply nested object schema and no annotations, the description supplies the essential behavioral warning (200 does not mean correct) and the fitting/geometry model that the schema alone does not convey as a coherent whole. An output schema exists, so the brief mention of returns is acceptable. It does not cover auth or failure classes beyond the 200 gotcha.
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 100% and the parameter docs are exhaustive, so the schema already carries the meaning; baseline is 3. The description reinforces the geometry notation ('full and full-N') and the text-fitting rationale, but those largely restate what the per-property descriptions already say, adding little net new per-parameter information.
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 — 'Render a layout at a given canvas size' — and immediately distinguishes itself from the sibling 'build_imagor_url' by scope (multi-slot layout vs. one image with typed parameters). An agent can tell this apart from parse_template and build_imagor_url 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?
Explicitly names an alternative and the condition that selects it: 'For one image with typed parameters and no layout, use build_imagor_url.' It also prescribes a workflow ('Verify it before handing it over'). It does not address the other siblings (parse_template, fit_text), so it stops short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse an imagor path and report whether it round-trips unchanged, plus a short summary of the transformation it describes. Use this to check a path before serving it. To convert an existing path into an editable layout, use parse_template.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | an imagor path to validate, without a leading slash and without any signature prefix |
| Name | Required | Description |
|---|---|---|
| path | Yes | the path as parsed |
| valid | Yes | whether the path is well formed and would not be silently ignored |
| stable | Yes | whether regenerating the parsed path reproduces the input exactly |
| rebuilt | Yes | the path regenerated from the parsed parameters |
| summary | Yes | a short description of the parsed transformation |
| problems | No | reasons imagor would ignore this path or fail to load it |
| warnings | No | things imagor accepts but may not act on |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the nature of the result (round-trip check plus a short summary) and is implicitly a read-only analysis, but it says nothing about how malformed or invalid paths are surfaced (error vs. reported failure), which is the key behavioral question for a validation tool.
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?
Three short sentences, front-loaded with the core behavior, followed by the usage cue and the sibling routing. No filler, and every sentence 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?
With an output schema present, return values need not be explained, and the description covers purpose, usage timing, sibling routing, and the input constraint. Nothing essential for a correct invocation 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?
There is a single parameter with 100% schema description coverage; the schema already documents the leading-slash and signature-prefix constraints, and the description adds no further format or syntax detail. Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('parse an imagor path and report whether it round-trips unchanged') plus the secondary output (transformation summary). It also distinguishes itself from the similarly named sibling by naming parse_template and its different purpose, so an agent can route correctly 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?
'Use this to check a path before serving it' gives an explicit when, and the final sentence names the alternative (parse_template) together with the condition that selects it (converting a path into an editable layout). Both the use case and the exclusion are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the result for a composition from the running imagor and report what it did with each filter: applied, declined, or not reported, plus the dimensions the server reported. Answers whether a composition actually does what it says, which the build tools cannot know on their own. Takes the same typed parameters as build_imagor_url, not a URL. Requires IMAGOR_BASE_URL. A server that does not report filter outcomes returns unknown for every filter and verified: false, which means the result is unknown rather than wrong. Compare the reported dimensions and outcomes against what you intended, and fetch the result to compare it against your reference: a composition can succeed and still be wrong. The rendered result is attached as an image by default, so you can see what you built rather than only reading what the server did with it - use it to check placement, cropping and text against your reference, and iterate until it matches. The image is scaled down, so it shows the layout and not fine detail. Pass preview: false to get the report alone when you do not need to look.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | return image metadata only, without processing the image | |
| trim | No | trim surrounding space using the top-left pixel colour | |
| image | Yes | the source to transform, not a composed result: a URL or path such as "example.com/a.jpg", or a synthetic source such as "color:red" or "color:none" | |
| smart | No | use content-aware smart crop | |
| width | No | target width in pixels; 0 means automatic | |
| fit_in | No | fit inside width x height instead of cropping to fill; the result can be smaller than the box on one side | |
| h_flip | No | mirror horizontally | |
| height | No | target height in pixels; 0 means automatic | |
| v_flip | No | mirror vertically | |
| filters | No | ordered filters, applied left to right. Arguments are validated against imagor's catalogue: call list_imagor_filters for a filter's signature, description and accepted argument forms. image() loads its argument as its own canvas, so positions inside it are relative to the overlay | |
| h_align | No | horizontal alignment, either "left" or "right" | |
| preview | No | attach the rendered result as an image, so a composition that succeeded but came out wrong can be seen. Defaults to true | |
| stretch | No | stretch to exactly width x height, ignoring aspect ratio, which distorts the image; use full_fit_in to fill a box of a different shape without distorting it | |
| trim_by | No | trim anchor, either "top-left" or "bottom-right" | |
| v_align | No | vertical alignment, either "top" or "bottom" | |
| crop_top | No | crop top edge: a fraction 0-1 of the height, or absolute pixels when greater than 1 | |
| crop_left | No | crop left edge: a fraction 0-1 of the width, or absolute pixels when greater than 1 | |
| crop_right | No | crop right edge: a fraction 0-1 of the width, or absolute pixels when greater than 1 | |
| crop_bottom | No | crop bottom edge: a fraction 0-1 of the height, or absolute pixels when greater than 1 | |
| full_fit_in | No | cover the box without cropping: one side matches width x height and the other exceeds it, keeping the aspect. Use for an image that must fill a panel without cutting into it. Requires fit_in, and add upscale() when the source is smaller than the box | |
| allow_declined | No | return the report instead of an error when a filter was recognised but left the image unchanged. Set this for a filter that is deliberately conditional; leave it unset to treat a decline as the failure it usually is | |
| preview_region | No | attach part of the result at native resolution as x,y,w,h in result pixels, for checking text and fine detail that a scaled preview cannot show. Takes precedence over preview | |
| trim_tolerance | No | trim tolerance from 0 to 255 | |
| adaptive_fit_in | No | invert width and height when that yields better definition; requires fit_in | |
| max_age_seconds | No | add a max_age() filter limiting how long the response may be cached | |
| expire_unix_millis | No | add an expire() filter so the URL stops working after this unix-milliseconds timestamp |
| Name | Required | Description |
|---|---|---|
| url | No | a request path ready to send to imagor, including its signature or unsafe prefix |
| mode | Yes | how the path was produced: signed or unsafe |
| note | No | human-readable notes about the result |
| path | Yes | the imagor path, without any signature or unsafe prefix |
| width | No | the result width the server reported, 0 when it reported none |
| height | No | the result height the server reported, 0 when it reported none |
| server | Yes | |
| signed | Yes | whether the URL carries a signature |
| status | Yes | the HTTP status the metadata request returned |
| results | No | |
| meta_url | No | the request path for the metadata that was read; its signature differs from the image URL because the signature covers the whole path |
| verified | Yes | |
| warnings | No | compositions that are valid but will not do what was intended |
| absolute_url | No | the full URL to fetch, present only when IMAGOR_BASE_URL is configured |
| meta_absolute_url | No | the full metadata URL that was fetched, present only when IMAGOR_BASE_URL is configured |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses the IMAGOR_BASE_URL requirement, that a non-reporting server yields unknown for every filter and verified:false (unknown, not wrong), that a composition can succeed and still be wrong, and that the preview is scaled down so only layout, not fine detail, is visible. These are behavioral traits an agent needs and cannot get from schema alone.
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?
Purpose and the key distinction from build tools are front-loaded, and most sentences carry real information (failure mode, comparison workflow, preview tradeoff). It is on the long side and repeats the 'look at the result vs. read the report' idea across several sentences, so it is efficient but not maximal.
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?
For a 26-parameter tool with an output schema and no annotations, the description covers the prerequisite, the failure/verification semantics, the preview tradeoff, and points to list_imagor_filters for filter signatures (via the schema). Return-value detail is correctly delegated to the output schema, so nothing essential 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 coverage is 100%, so baseline is 3, and the description adds some meaning beyond it: it clarifies that parameters are passed typed rather than as a pre-built URL, explains the preview default and its scaled-down nature, and tells the agent preview_region takes precedence when fine detail matters. The remaining parameter details are already in the schema, so it is a modest addition rather than a transformation.
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+resource: fetch the result of a composition from the running imagor and report what it did with each filter (applied/declined/not reported) plus reported dimensions. It also distinguishes itself from the sibling build_imagor_url by noting it takes the same typed parameters, not a composed URL, so an agent can route correctly 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?
Gives clear context and rationale: this answers whether a composition actually does what it says, which the build tools cannot know on their own, and it should be compared against intent and a reference. It also notes when to drop the image (preview: false). It stops short of an explicit 'use build_imagor_url first, then this' workflow statement, so 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.7.10parse_template2 fields changedOutput schema / properties / slots / items / properties / filters / descriptionPrevious value: -"for image or rect: filters applied to this slot's own source, written without the filters: prefix, e.g. smart/filters:round_corner(230,230,fff)"New value: +"for image or rect: filters applied to this slot's own source, colon-separated, for example smart():round_corner(230,230,fff). The filters: prefix is added for you. Measured: a slash between filters 404s"Output schema / properties / slots / items / properties / slots / items / properties / filters / descriptionPrevious value: -"for image or rect: filters applied to this slot's own source, written without the filters: prefix, e.g. smart/filters:round_corner(230,230,fff)"New value: +"for image or rect: filters applied to this slot's own source, colon-separated, for example smart():round_corner(230,230,fff). The filters: prefix is added for you. Measured: a slash between filters 404s"render_template2 fields changedInput schema / properties / slots / items / properties / filters / descriptionPrevious value: -"for image or rect: filters applied to this slot's own source, written without the filters: prefix, e.g. smart/filters:round_corner(230,230,fff)"New value: +"for image or rect: filters applied to this slot's own source, colon-separated, for example smart():round_corner(230,230,fff). The filters: prefix is added for you. Measured: a slash between filters 404s"Input schema / properties / slots / items / properties / slots / items / properties / filters / descriptionPrevious value: -"for image or rect: filters applied to this slot's own source, written without the filters: prefix, e.g. smart/filters:round_corner(230,230,fff)"New value: +"for image or rect: filters applied to this slot's own source, colon-separated, for example smart():round_corner(230,230,fff). The filters: prefix is added for you. Measured: a slash between filters 404s"v0.1.0build_imagor_urldescribe_imagorfit_textget_cookbook_recipeget_imagor_skilllist_imagor_filtersparse_templaterender_templatevalidate_imagor_pathverify_imagor_urlScored across 10 tools
Most tools have clearly distinct purposes, and descriptions actively cross-reference each other to guide selection (e.g., build_imagor_url vs render_template, parse_template vs validate_imagor_path). However, a few pairs still have overlapping surface areas—both build_imagor_url and render_template produce URLs, and both parse_template and validate_imagor_path parse paths—so an agent could momentarily confuse them, even though the descriptions resolve it.
All names use snake_case and follow a verb_noun pattern consistently. The only noticeable deviation is that some nouns include the 'imagor' prefix (build_imagor_url, describe_imagor, validate_imagor_path) while others do not (parse_template, render_template, fit_text), making the pattern slightly less predictable.
Ten tools is well within the ideal range and each seems to earn its place. Core operations (build, verify, render, parse, validate, fit_text) are complemented by focused reference tools (skill, filters, grammar, recipes) without obvious bloat or redundancy.
The surface covers the full lifecycle for imagor URL and template work: guidance, filter reference, recipe retrieval, template rendering, path parsing, URL building, verification, and text fitting. There are no obvious dead ends for composing, validating, or iterating on imagor paths and layouts.
Generate on-brand images from your AI agent: design, edit, and render templates over MCP.
Give agents instant OG image generation, social metadata audits, and rendering guidance.
Create images & video from any MCP agent — 17 models, spend limits, one URL.
Brand-safe MCP for AI agents to create editable, on-brand graphics and automate variants.
