MagicPixel

Upload style reference

upload_style_reference

Upload an image into the signed-in user's MagicPixel References library (same as in-app References + / AI picker Save). Returns style_reference_id for generate_pixel_art and apply_with_ai. Prefer PNG/JPEG for MCP generation (WebP/GIF store OK but generation gates require PNG/JPEG). Does not spend credits.

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": {
      "name": "<name>",
      "image_base64": "<image_base64>"
    },
    "name": "upload_style_reference"
  }
}

Input Schema

Name	Required	Description
`name`	Yes	Display name in the MagicPixel References library.
`folder_id`	No	Optional References folder id (create_folder with scope 'reference'). Must belong to the same project.
`project_id`	No	Scope the reference to this project (list_projects). Omitted → user's oldest project when one exists (same visibility rule as generate_pixel_art).
`image_base64`	Yes	Prefer PNG or JPEG (raw base64 or data URL). WebP/GIF upload for the References library, but MCP generation (generate_pixel_art / apply_with_ai) requires PNG/JPEG so spritesheet safety can be checked. Max ~5 MB decoded.

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.4/5.0

Behavior4/5

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

Annotations declare a non-read-only, non-destructive, non-idempotent write, and the description adds meaningful context beyond them: it does not spend credits, it surfaces format gating that will block later generation, and it names the returned identifier. It does not cover error behavior (e.g., what happens on duplicate names or invalid project_id), which keeps it below a 5.

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?

Dense and front-loaded — purpose first, then return value, then format constraints, then cost. The parenthetical asides are slightly nested but each sentence carries distinct information, with no filler.

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?

No output schema exists, yet the description names the return field (style_reference_id) and its consumers, covers cost and format constraints, and annotations handle the safety profile. An agent has everything needed to call this correctly on the first attempt.

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 100%, so the baseline is 3, but the description adds consequence-level meaning the schema lacks: the WebP/GIF-versus-PNG/JPEG distinction is framed as a downstream generation gate rather than a mere preference, and project_id's default behavior is reinforced in prose.

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 (upload an image into the user's References library) and disambiguates by mapping it to the in-app 'References + / AI picker Save' flow, which separates it from sibling style tools like add_style_sample or get_style_reference.

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 operative guidance: it is the step to run before generate_pixel_art or apply_with_ai, and it explicitly recommends PNG/JPEG for generation while noting WebP/GIF are acceptable only for storage. It does not state when to choose this over alternatives such as add_style_sample, so it stops short of full routing guidance.

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

All MagicPixel tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?