Skip to main content
Glama

Replace images on a site

regenerate_images
Idempotent

Find or make new images for the given image_ids: first matches from the account's image library, then professional stock photography, then AI generation. By default the top find replaces each image on the site (recorded in version history); apply: false returns candidates to choose from instead, committed with apply_image_replacements. May SPEND Creative Credits, only for images that need AI generation: call plan_image_regeneration first and send its credits as expected_credit_cost with a stable idempotency_key. A different price is refused with nothing charged.

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": {
      "site_id": "<site_id>",
      "image_ids": "<image_ids>",
      "expected_credit_cost": "<expected_credit_cost>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "regenerate_images"
  }
}

Input Schema

NameRequiredDescriptionDefault
applyNoDefault true: put the top find on the site. false: only return candidates to choose from, then apply_image_replacements.
site_idYesThe site to act on
image_idsYesThe image_id values from plan_image_regeneration to replace.
user_goalNoOptional: the user's goal behind this call, in one short sentence of plain words (e.g. "add a page so customers can book tables"). No names, emails or other personal details.
style_hintNoVIBE: how the images should feel ("warm photography"), not what they show.
user_promptNoSUBJECT, when the user named one ("a red sports car"): every image will depict it. Their literal words.
variation_idNoThe design to work on. Omit for the site's live design.
idempotency_keyYesStable key for this attempt; reuse it on a retry so nothing is charged twice
expected_credit_costYes`credits` from plan_image_regeneration for these images (0 when the plan uses its image allowance)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / user_goal
      Added value: +{
      +  "description": "Optional: the user's goal behind this call, in one short sentence of plain words (e.g. \"add a page so customers can book tables\"). No names, emails or other personal details.",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Adds real behavior beyond the annotations: it can SPEND Creative Credits, replacements are recorded in version history, a mismatched price is refused with nothing charged, and the idempotency key must be reused on retry. Annotations only give the generic safety profile (non-destructive, idempotent), so this context is genuinely additive; only the return shape of candidates is left implicit.

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-loaded with the core action and default behavior, then conditions, then the credit-safety prerequisite. Dense but every clause carries information; the middle sentence is long and could be split for easier scanning.

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?

Covers the mutation's side effects, cost gating, retry semantics, and the alternative commit path for a 9-parameter tool with no output schema. The only gap is that the shape of the returned candidates (when apply=false) isn't hinted at, which matters for a no-output-schema tool.

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 baseline is 3, but the description adds cross-tool meaning for three params: `apply` switches between apply/candidate modes, `expected_credit_cost` comes from plan_image_regeneration's `credits`, and `idempotency_key` must be stable across retries to avoid double charging. The remaining params (style_hint, user_prompt, variation_id) are left to the schema.

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 ('find or make new images for the given image_ids') plus the resolution order it uses (library → stock → AI) and the default outcome (top find replaces each image on the site). This clearly separates it from plan_image_regeneration (planning) and apply_image_replacements (committing candidates).

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?

Explicit routing: default applies the top find; `apply: false` returns candidates that are then committed with apply_image_replacements; and before spending credits the agent must call plan_image_regeneration and pass its `credits`. When-to-use, when-not, and the alternative are all named.

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