PicoBerry MCP Server

generate_image

Create 2D images from text prompts using PicoBerry's multi-engine API. Optionally add up to 4 reference images to guide results, then wait for the asset to finish before reading the PNG URL.

Instructions

Generate a 2D image from a text prompt (async). Returns an asset { id }; then call wait_for_asset (or poll get_asset) until taskStatus=2 and read files.image (PNG URL). Costs credits — see list_models(category='image'). Omit model for the default. Up to 4 reference image URLs can guide the result (best with nano-banana). Set count (1–4) for several images from one call: the top-level fields stay the first image and assets[] lists every image (same batchId) — wait_for_asset on each id. Each image is billed separately; if the balance can't cover all of them nothing is charged. A count above the plan's image slots fails with 400 (don't retry); a busy queue fails with 429 (retry later).

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": {
      "prompt": "<prompt>"
    },
    "name": "generate_image"
  }
}

Input Schema

Name	Required	Description
`count`	No	images to make in this call, 1–4 (default 1). Needs that many free image slots on the plan (Free 1 · Starter 3 · Pro 6 · Max 15).
`model`	No	engine name from list_models(category='image')
`prompt`	Yes
`aspect_ratio`	No	W:H, e.g. "1:1", "16:9", "9:16", "21:9". Use a value from the model's supportedAspectRatios in list_models(category='image') — nano-banana models reject anything else with 400 before charging credits; gpt-image-* buckets any ratio to its nearest of three output sizes.
`reference_image_urls`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.1.7Oct 26, 2026

addedInput schema / properties / count

Added value: +{
+  "description": "images to make in this call, 1–4 (default 1). Needs that many free image slots on the plan (Free 1 · Starter 3 · Pro 6 · Max 15).",
+  "maximum": 4,
+  "minimum": 1,
+  "type": "integer"
+}

Changed3 schema fields changedv0.1.6Sep 14, 2026

changedInput schema / properties / aspect_ratio / description

Previous value: -"e.g. \"1:1\", \"16:9\", \"9:16\""New value: +"W:H, e.g. \"1:1\", \"16:9\", \"9:16\", \"21:9\". Use a value from the model's supportedAspectRatios in list_models(category='image') — nano-banana models reject anything else with 400 before charging credits; gpt-image-* buckets any ratio to its nearest of three output sizes."

addedInput schema / properties / aspect_ratio / pattern
```
Added value: +"^[1-9]\\d?:[1-9]\\d?$"
```
changedInput schema / properties / prompt / maxLength
```
Previous value: -5000New value: +4000
```

First observedv0.1.0Jul 14, 2026

TDQS

A4.6/5.0

Behavior4/5

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

With no annotations, the description carries the whole burden and does it well: async lifecycle, credit cost, per-image billing, the no-charge-on-insufficient-balance guarantee, 400 = don't retry (plan slot limit) and 429 = retry later. Missing only auth/permission prerequisites, which are minor here.

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?

Front-loads the core action and lifecycle, then layers cost, batching, and error handling in a logical order. It is dense but nearly every clause carries operational information; a very slight trim of the batching paragraph would tighten it.

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?

With no output schema, the description still defines the return shape ({id}, files.image PNG URL, assets[] with shared batchId) and the full success/failure path. Nothing an agent needs to invoke and complete the workflow is absent.

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 60%, and the description compensates for `model` (default behavior) and `reference_image_urls` (up to 4, best with nano-banana) plus the batch semantics of `count` including the assets[] return shape. `aspect_ratio` detail is left entirely to the schema, so it stops short of full coverage.

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+resource ("Generate a 2D image from a text prompt"), flags the async contract immediately, and is clearly distinguishable from the generate_3d_* siblings.

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

Usage Guidelines5/5

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

Explicitly names the follow-up path (call wait_for_asset or poll get_asset until taskStatus=2), tells the agent to omit `model` for the default, and points to list_models(category='image') for engine/credit lookup. It also gives conditional guidance for `count` and `reference_image_urls`.

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

Deploy Server