Skip to main content
Glama

image_to_braille

Convert images into sharp Unicode braille art and stamp them onto the canvas at a chosen position. Use it for detailed photo, logo, or silhouette rendering with dithering or clean edge outlines.

Instructions

Convert an image file (png, jpg, webp, ...) into high-resolution Unicode braille art and stamp it onto the canvas at (x, y). Each braille cell holds a 2x4 dot grid, so this renders at 2x the horizontal and 4x the vertical resolution of image_to_ascii — the sharpest photo/logo/silhouette rendering here. Dots are 1-bit, so dithering (on by default) fakes tone. The image is fitted to max_width braille cells (rows follow the 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_braille"
  }
}

Input Schema

NameRequiredDescriptionDefault
xNo
yNo
pathYesAbsolute or relative path to the image file.
edgesNoOutline mode: light dots only along steep brightness gradients, turning the image into a clean braille line drawing (ignores dither/tone).
gammaNoMidtone gamma. 1 = off; <1 deepens shadows, >1 lifts them.
ditherNo1-bit tone: 'floyd' = Floyd–Steinberg grain (default, best for photos), 'bayer' = ordered cross-hatch, 'none' = hard threshold for line art.floyd
invertNoFlip which pixels light a dot — use for dark subjects on a light background.
max_widthNoTarget width in braille cells (each cell is 2 sub-pixels wide).
thresholdNoDot cutoff 0..1 for dither='none' (crisp line art). Ignored when dithering.
transparentNoComposite over existing art — skip blank cells (braille-blank / space) so the render layers on top instead of erasing the background.
auto_contrastNoStretch the brightness range for a sharper result.
edge_thresholdNoEdge sensitivity 0..1 for `edges` (lower = more contour detail).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does substantial work: it discloses the 1-bit dot model, that dithering is what fakes tone, that max_width controls fitting with rows following aspect ratio, and that it returns the placed size. It stops short of stating failure behavior for bad paths, how it handles content outside the canvas bounds, or that existing canvas art is overwritten unless composited.

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?

Four sentences, front-loaded with the verb and destination, then the resolution differentiator, then the mechanism, then the return value. No filler and no repetition of schema content for its own sake.

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

Completeness4/5

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

For a 12-parameter tool with an output-schema gap, the description covers the critical unknowns: output resolution, tone mechanism, sizing model, and the return value. What remains uncovered is error handling on unreadable paths and the exact overwrite semantics on the target canvas.

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 83%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that max_width is measured in braille cells and drives aspect-ratio-derived row count, and that dither is the switch enabling tone. Pixel-level parameters like threshold, gamma and edge_threshold are left entirely to their schema descriptions.

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?

States a specific verb and resource ('Convert an image file ... into high-resolution Unicode braille art') plus the exact placement effect ('stamp it onto the canvas at (x, y)'). It explicitly differentiates from the sibling image_to_ascii by dot-grid ratio and calls itself 'the sharpest photo/logo/silhouette rendering here', so an agent can choose without opening a schema.

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?

Gives clear context for selection: best for photos, logos and silhouettes, and positioned as higher resolution than image_to_ascii. It also implies mode routing ('dithering ... on by default' fakes tone, edges mode for line drawings) though it never states an explicit when-not-to-use case or names a different tool to prefer for text or diagrams.

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