Skip to main content
Glama

Generate design candidates

design_generate_candidates
Destructive

Generate several candidate designs for ONE brief so the user can pick.

A design usually starts here: the user describes what they want and gets three options back. For a single design, or to refine one they already picked, use design_start_for_order.

prompt MUST be the user's own description of the piece. Never synthesise a brief, and never treat their choice of the design route as a description of the artwork: if they have not said what they want, ask before calling this. Each call spends count real generations, so a guessed brief wastes them all and shows the user designs for something they never asked for.

Pass the order_id and the design brief; it provisions count designs (default 3) against the order's real geometry, generates each in parallel, and returns them as candidates — each with a design_id, a short summary, a design_url, and thumbnails. Pass item_id to design one item; it is required when the order has several items (OrderItemRequiredError lists them). Each item keeps its own design, so the items of an order can be designed side by side. On an order with several items, an item whose design is already attached fails with DesignAttachedError, because that design is final. An item whose uploaded file has a submitted page mapping fails with UploadMappingSubmittedError, because that file prints.

Present every candidate to the user as a numbered markdown link to its thumbnail (and design_url) so they SEE each option — never only the text summary — and use those URLs EXACTLY as returned (never build or guess one). Number them in the order returned: the user may reply by position ("design nr 2"), so map that number back to candidates[n-1].design_id yourself. A candidate with thumbnails_pending: true has no preview yet: its image is still rendering, and it may not become available. Still offer it and link its design_url. Tell the user that the preview is still rendering and may not be available, and that they can choose the design or open it in the editor anyway. Do not say that the preview will appear. Then let the USER choose and call design_pick_candidate with their chosen design_id before any design_chat; the unpicked candidates are dropped. While a batch is unpicked, a new call fails with CandidatePendingError. If the customer rejected every candidate, offer a new batch. Call again with discard_unpicked=true only after they say yes: it drops the unpicked batch. Each order item gets at most 3 batches (CandidateBatchLimitError).

Returns a job — poll with poll_job until SUCCEEDED.

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": {
      "session_id": "<session_id>",
      "order_id": "<order_id>",
      "prompt": "<prompt>"
    },
    "name": "design_generate_candidates"
  }
}

Input Schema

NameRequiredDescriptionDefault
countNo
promptYes
item_idNo
order_idYes
session_idYes
discard_unpickedNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true, but the description goes far beyond them: it discloses that each call spends `count` real paid generations, provisions against the order's real geometry, generates in parallel, that unpicked candidates are dropped, that a batch blocks new calls with `CandidatePendingError`, and that each item is capped at 3 batches. It also discloses `discard_unpicked` semantics and the job-polling return contract — exactly the cost/destructiveness context an agent needs.

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?

The purpose and the alternative route are front-loaded, and most sentences carry operational weight. It runs long, though: the thumbnail-rendering instructions and the numbered-link presentation rule are repeated across several sentences and could be tightened without losing meaning.

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?

For a destructive, non-idempotent, multi-error tool with a job-based async return, the description covers invocation preconditions, cost, error branches, output shape, and the required follow-up tool. Even though an output schema exists, the candidate fields and the poll-with-`poll_job` requirement are stated, leaving nothing an agent needs in order to call it correctly.

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 description coverage is 0%, so the description must carry the load, and it does for nearly every parameter: `prompt` must be the user's own words (never synthesised), `count` is real generations spent with default 3, `item_id` is required on multi-item orders and triggers `OrderItemRequiredError`, `discard_unpicked` only after user consent. Only `session_id` is left unexplained, a minor gap for an otherwise strong semantic layer.

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 ('Generate several candidate designs') plus an explicit scope constraint ('for ONE brief so the user can pick'), then immediately names the sibling `design_start_for_order` for the single-design case. An agent can distinguish this from every other design_* tool 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 Guidelines5/5

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

Gives when-to-use (user describes what they want, wants options), when-to-use-instead (single design or refining an already-picked design → `design_start_for_order`), and an explicit when-NOT-to-call: if the user has not said what they want, ask first. It also sequences the flow (pick via `design_pick_candidate` before any `design_chat`, offer a new batch after rejection) and enumerates the errors that block a call.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources