Skip to main content
Glama

place

Idempotent

Set a shot’s location using style presets, colors, sky, and scenery items; invalid IDs are refused, and the updated location and item IDs return as one undo step.

Instructions

Set where a shot happens: a place preset (with its scenery), and/or its colours and sky, and scenery items. Ids must come from the current style: call library to see them (a wrong id is refused with the valid list). Returns the place and its item ids. One undo step for the person. For a generated photo background use generate_place; for your own picture use upload with as background.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "place"
  }
}

Input Schema

NameRequiredDescriptionDefault
orbNoSun, moon or none.
skyNoSky colour, "#RRGGBB".
darkNotrue: a dark place (night, inside).
nameNoA name for the place.
shotNoThe shot's id (from get_project). Left out: the shot on screen.
floorNoFloor colour, "#RRGGBB".
starsNoShow stars.
wallsNoShow walls (an inside place).
cloudsNoShow clouds.
presetNoPlace preset id (library places).
horizonNoHorizon colour, "#RRGGBB".
add_itemsNoScenery items to add.
clear_itemsNotrue: remove every scenery item.
change_itemsNoScenery items to change.
remove_itemsNoItem ids to remove.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed23 schema fields changedv0.1.2
    • addedInput schema / properties / add_items / description
      Added value: +"Scenery items to add."
    • addedInput schema / properties / add_items / items / properties / kind / description
      Added value: +"An object or place id of the style."
    • addedInput schema / properties / add_items / items / properties / size / description
      Added value: +"1 is normal."
    • addedInput schema / properties / add_items / items / properties / x / description
      Added value: +"Left (-) / right (+)."
    • addedInput schema / properties / add_items / items / properties / z / description
      Added value: +"Near (+) / far (-), about -3 to -30."
    • addedInput schema / properties / change_items / description
      Added value: +"Scenery items to change."
    • addedInput schema / properties / change_items / items / properties / id / description
      Added value: +"Item id from get_shot."
    • addedInput schema / properties / change_items / items / properties / kind / description
      Added value: +"Swap to another object id."
    • addedInput schema / properties / change_items / items / properties / size / description
      Added value: +"1 is normal."
    • addedInput schema / properties / change_items / items / properties / x / description
      Added value: +"Left / right."
    • addedInput schema / properties / change_items / items / properties / z / description
      Added value: +"Near / far."
    • addedInput schema / properties / clear_items / description
      Added value: +"true: remove every scenery item."
    • addedInput schema / properties / clouds / description
      Added value: +"Show clouds."
    • addedInput schema / properties / dark / description
      Added value: +"true: a dark place (night, inside)."
    • addedInput schema / properties / floor / description
      Added value: +"Floor colour, \"#RRGGBB\"."
    • addedInput schema / properties / horizon / description
      Added value: +"Horizon colour, \"#RRGGBB\"."
    • addedInput schema / properties / name / description
      Added value: +"A name for the place."
    • addedInput schema / properties / orb / description
      Added value: +"Sun, moon or none."
    • addedInput schema / properties / preset / description
      Added value: +"Place preset id (library places)."
    • changedInput schema / properties / remove_items / description
      Previous value: -"Item ids."New value: +"Item ids to remove."
    • addedInput schema / properties / sky / description
      Added value: +"Sky colour, \"#RRGGBB\"."
    • addedInput schema / properties / stars / description
      Added value: +"Show stars."
    • addedInput schema / properties / walls / description
      Added value: +"Show walls (an inside place)."
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Beyond the annotations it discloses error behavior (a wrong id is refused with the valid list), the return value (the place and its item ids), and undo granularity ('One undo step for the person'), which is valuable for a mutation tool. It does not explain interaction between parameters, e.g. whether a preset overwrites explicit colours or sky, leaving the main behavioral ambiguity unresolved.

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?

It is short, front-loaded with the purpose, and every clause carries information (scope, id sourcing, return, undo, alternatives). The 'and/or its colours and sky, and scenery items' phrasing is slightly tangled but not wasteful.

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 15-parameter mutation tool with no output schema, it covers the essentials: what it sets, where ids come from, failure behavior, return values, undo, and sibling routing. The only real gap is how preset and the explicit colour/sky parameters combine when both are supplied.

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 100%, so the baseline is 3, but the description adds meaning the schema lacks: ids must come from the current style and a bad id is rejected with the valid list, and a preset carries its own scenery. That constraint is not encoded in the input schema and materially changes how an agent gathers ids first.

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?

The description names a specific verb and resource: 'Set where a shot happens', then enumerates the settable facets (preset with scenery, colours, sky, scenery items). It explicitly distinguishes itself from generate_place and upload, so an agent can choose it without opening the 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?

It gives explicit routing conditions: 'For a generated photo background use generate_place; for your own picture use upload with as background', plus the prerequisite 'call library to see them' for ids. Both alternatives and the condition that selects them are stated, not implied.

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