Skip to main content
Glama

Embers: Tabletop RPG Toolkit

Update an imagine world

imagine_update_world
Idempotent

PUT updates to one world by id. Caller must have 'edit' access (the owner, a contributor, or an admin with Admin Mode on). showInvite changes only for the world's owner or an admin with Admin Mode on; from a contributor it is ignored. Only supplied fields are sent; imagine merges them onto the existing document. REQUIRES baseUpdatedAt: copy updatedAt from a fresh imagine_get_world read; a stale or fabricated value is rejected with OUT_OF_SYNC and nothing is written.

Input Schema

NameRequiredDescriptionDefault
idYesMongo `_id` of the world.
linkNoURL-safe slug for the world (lowercase letters, digits, hyphens). Imagine auto-suggests at create time when omitted.
menuNoSite menu entries — label + optional link/pageId/order.
nameNoWorld name.
imageNo
activeNo
publicNoWhether the world is public. Only Premium, VIP, and admin accounts can change whether a world is public; the server refuses the change from anyone else. A new world is public unless set otherwise.
faviconNo
summaryNoShort summary; capped at 255 characters. Cross-app convention (per dev-sites/AGENTS.md); the Mongoose World schema still accepts up to 500 as a legacy inconsistency being migrated, but new authoring should keep summaries under 255.
calendarNoOptional calendar definition (months[] + eras[]).
keywordsNo
showInviteNoWhether the world's public page shows an invite button. Only the world's owner or an admin with Admin Mode on can change it; a contributor's value is ignored.
descriptionNoFull world description. Markdown supported.
customDomainNoOptional custom domain pointing at the world's public site.
baseUpdatedAtYesREQUIRED proof that you are working from the latest version: copy the `updatedAt` value verbatim from a FRESH read of this exact record (use the matching get tool first). Values from memory, from an earlier conversation, or guessed timestamps are rejected with OUT_OF_SYNC and nothing is written. After a successful update, the response carries the new `updatedAt` — use that for any follow-up write.
imageCarouselNo
isExampleWorldNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / showInvite / description
      Added value: +"Whether the world's public page shows an invite button. Only the world's owner or an admin with Admin Mode on can change it; a contributor's value is ignored."
  2. Changed20 schema fields changed
    • addedInput schema / $schema
      Added value: +"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +{}
    • addedInput schema / properties / active
      Added value: +{
      +  "type": "boolean"
      +}
    • addedInput schema / properties / baseUpdatedAt
      Added value: +{
      +  "description": "REQUIRED proof that you are working from the latest version: copy the `updatedAt` value verbatim from a FRESH read of this exact record (use the matching get tool first). Values from memory, from an earlier conversation, or guessed timestamps are rejected with OUT_OF_SYNC and nothing is written. After a successful update, the response carries the new `updatedAt` — use that for any follow-up write.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / calendar
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Optional calendar definition (months[] + eras[]).",
      +  "properties": {
      +    "eras": {
      +      "items": {
      +        "additionalProperties": {},
      +        "properties": {
      +          "name": {
      +            "type": "string"
      +          },
      +          "order": {
      +            "type": "number"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "months": {
      +      "items": {
      +        "additionalProperties": {},
      +        "properties": {
      +          "name": {
      +            "type": "string"
      +          },
      +          "order": {
      +            "type": "number"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / customDomain
      Added value: +{
      +  "description": "Optional custom domain pointing at the world's public site.",
      +  "type": "string"
      +}
    • addedInput schema / properties / description
      Added value: +{
      +  "description": "Full world description. Markdown supported.",
      +  "type": "string"
      +}
    • addedInput schema / properties / favicon
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / id
      Added value: +{
      +  "description": "Mongo `_id` of the world.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / image
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / imageCarousel
      Added value: +{
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / isExampleWorld
      Added value: +{
      +  "type": "boolean"
      +}
    • addedInput schema / properties / keywords
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / link
      Added value: +{
      +  "description": "URL-safe slug for the world (lowercase letters, digits, hyphens). Imagine auto-suggests at create time when omitted.",
      +  "type": "string"
      +}
    • addedInput schema / properties / menu
      Added value: +{
      +  "description": "Site menu entries — label + optional link/pageId/order.",
      +  "items": {
      +    "additionalProperties": {},
      +    "properties": {
      +      "label": {
      +        "description": "Required by Mongoose.",
      +        "type": "string"
      +      },
      +      "link": {
      +        "type": "string"
      +      },
      +      "order": {
      +        "type": "number"
      +      },
      +      "pageId": {
      +        "description": "Mongo `_id` reference (24-character hex string).",
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / name
      Added value: +{
      +  "description": "World name.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / public
      Added value: +{
      +  "description": "Whether the world is public. Only Premium, VIP, and admin accounts can change whether a world is public; the server refuses the change from anyone else. A new world is public unless set otherwise.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / showInvite
      Added value: +{
      +  "type": "boolean"
      +}
    • addedInput schema / properties / summary
      Added value: +{
      +  "description": "Short summary; capped at 255 characters. Cross-app convention (per dev-sites/AGENTS.md); the Mongoose World schema still accepts up to 500 as a legacy inconsistency being migrated, but new authoring should keep summaries under 255.",
      +  "maxLength": 255,
      +  "type": "string"
      +}
    • addedInput schema / required
      Added value: +[
      +  "id",
      +  "baseUpdatedAt"
      +]
  3. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Goes well beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing merge semantics ('only supplied fields are sent; imagine merges them'), optimistic-concurrency behavior (stale/fabricated baseUpdatedAt → OUT_OF_SYNC with nothing written), and field-level permission nuance (showInvite ignored for contributors). This is exactly the extra context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the operation, then permissions, then merge behavior, then the critical baseUpdatedAt requirement. Four tight sentences with no filler; each clause carries actionable information.

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 17-parameter, nested-object mutation tool with an output schema, the description covers the highest-risk aspects (access control, merge semantics, concurrency guard) and defers return values to the output schema. Nothing essential to a correct invocation is missing.

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 65%, but the description compensates by explaining the two most consequential parameters: baseUpdatedAt (how to obtain it, why it is required, the rejection behavior) and showInvite (who may change it). It does not add syntax detail for the remaining nested/optional fields, which the schema partially covers.

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 with explicit scope: 'PUT updates to one world by id.' It also names the sibling read tool (imagine_get_world) it depends on, so an agent can distinguish this world-level update from the world-page and adventure update siblings 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 Guidelines4/5

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

Gives clear prerequisites (must have 'edit' access as owner, contributor, or admin with Admin Mode) and the mandatory workflow (copy updatedAt from a fresh imagine_get_world read first). It does not explicitly name when to choose this over imagine_update_world_page, but the context is strong.

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