Skip to main content
Glama

image_to_ascii

Convert an image file into ASCII art by brightness and stamp it onto the current canvas at specified coordinates, returning the placed size for layout.

Instructions

Convert an image file (png, jpg, webp, ...) into ASCII by brightness and stamp it onto the current canvas at (x, y). Ideal for photo/logo density art. Uses jp2a's fine 23-step tonal ramp by default for smooth gradation. The image is fitted to max_width columns (rows are derived from its aspect ratio). Returns the placed size so you can size the canvas first.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>"
    },
    "name": "image_to_ascii"
  }
}

Input Schema

NameRequiredDescriptionDefault
xNo
yNo
pathYesAbsolute or relative path to the image file.
rampNoCustom density ramp from empty to full. Overrides `ramp_preset`.
edgesNoStructure-aware: draw contours as | - / \ strokes over the fill, for crisper silhouettes.
gammaNoMidtone gamma (extends jp2a's linear mapping). 1 = off; <1 deepens shadows, >1 lifts them.
ditherNoFake continuous tone from few ramp steps: 'bayer' = ordered cross-hatch, 'floyd' = Floyd–Steinberg grain. Pairs well with the 'blocks' or 'classic' ramp.none
invertNoFlip dark/bright — use for dark subjects on a light background.
max_widthNoTarget width in characters.
ramp_presetNoBuilt-in ramp: 'jp2a' = 23-step smooth tone, 'classic' = 10-step graphic, 'blocks' = solid shade blocks (░▒▓█), 'braille' = fine braille tone. Ignored if `ramp` is given.jp2a
transparentNoComposite over existing art — skip blank cells so the image layers on top instead of erasing the background.
auto_contrastNoStretch the brightness range to use the full ramp (sharper result).
edge_thresholdNoEdge sensitivity 0..1 (lower = more contour strokes).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A3.5/5.0
Behavior3/5

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

No annotations are supplied, so the description carries the full burden. It does disclose that the output is stamped onto the existing canvas and that the call returns the placed size, which is useful planning information. But it never states whether the stamp overwrites existing art (only the `transparent` parameter description implies that) or what happens if the canvas is too small or the path is invalid.

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?

Four compact sentences with the core action front-loaded, then defaults, then the return value. Nothing is redundant, though the ramp sentence partially restates the `ramp_preset` enum description and could be trimmed.

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?

For a 13-parameter mutation-style tool with no annotations and no output schema, the description covers the essential action, sizing model, and return value. It omits key operational facts: whether existing canvas content is erased, whether a canvas must already exist, and error behavior for bad paths or oversized dimensions.

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 strong at 85%, so the baseline is 3, but the description adds real meaning: the image is fitted to `max_width` columns with rows derived from aspect ratio, and the default ramp is the 23-step jp2a tonal ramp. This clarifies how max_width and ramp_preset actually affect output in ways the schema alone does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a concrete verb-and-resource pair: convert an image file into ASCII by brightness and stamp it onto the current canvas at (x, y). It also conveys the use case ('Ideal for photo/logo density art'), so an agent can tell it apart from a generic drawing tool. It does not explicitly differentiate itself from the sibling image_to_braille, which is the nearest ambiguity.

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

Usage Guidelines3/5

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

'Ideal for photo/logo density art' implies when to reach for this tool, and 'so you can size the canvas first' hints at an ordering dependency with canvas sizing. However, there is no explicit statement of when NOT to use it or which sibling (e.g. image_to_braille, draw_icon) to pick instead, leaving the routing decision to inference.

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