Skip to main content
Use edit_world to change apps and starting data for future runs, or records in the instance your agent is using. Choose the target for your change: Connect to the Hue MCP server with Read and write access. On an organization connection, pass the chosen project_id in every call.

Change starting data for future runs

Ask your coding agent to change a World in your selected project:
Prompt
Your coding agent passes the description to edit_world. Hue runs its own model to inspect the selected World’s redacted records and prepare changes. Hue validates those changes and publishes a new version under the same World. Existing versions and running instances keep their data. If Hue needs clarification, it returns status: needs_input and a question without publishing. To call the tools directly:
  1. Call list_worlds, then get_world_definition to select the World and its latest version.
  2. Call edit_world with world_definition_id, world_version_id, an idempotency_key, and a description of the change. Use dry_run: true to validate without publishing.
Description edits use your organization’s AI budget. A published description edit consumes one trial creation allowance. A dry run still uses the model, so publishing afterward incurs a separate model call. Descriptions accept up to 32,000 characters. Each request has at most 32 model steps and a 90-second model deadline. Failed or invalid proposals publish nothing. For explicit changes without a Hue model call, inspect get_world_edit_context with the same World and version. Select a returned collection to read its schema, identity, references, and protected fields. Add include_content: true to read redacted records. Content reads are audited. Pass changes_json to edit_world instead of description. Each record change in changes_json names a collection and entityId. add supplies a complete schema-valid value. update supplies top-level fields to set or remove, preserving every unnamed field. delete removes a record. Include related record changes in the same batch so references still resolve. For example, replace the collection binding and channel ID below with values from the context tool:
An update replaces each named top-level value in full, including a nested object. Do not copy redaction placeholders into edits or author protected recorded fields. If records span content_json pages, keep the same selectors and join the pages using content_next_offset before advancing next_cursor. Publish with dry_run: false. Reuse the same key only for an identical retry of that publication. If that description edit is still running, retry the same request after it finishes. Completed retries return the saved result without another model call. If another edit publishes first, inspect the latest version and prepare a new edit. Start a fresh instance from the returned version.id when you want to use the changes. One edit accepts up to 10,000 app or record changes and 768 KiB of changes, for Worlds up to 125,000 records and 256 MiB. The full MCP request must also fit 1 MiB. These are separate limits; each request must also finish within MCP’s 100-second execution deadline. Split larger edits into requests, using each returned version for the next edit. Keep related record changes together so references resolve. The World must use supported app instances. Existing app bindings and configuration stay fixed. Existing principal and workspace records are protected, except editable connected workspaces reported by get_world_edit_context. Records referenced by the acting principal, including its own user, are also read-only. Other people remain editable.

Add or remove an app

Ask your coding agent to add a supported app with related records or remove an existing app:
Prompt
get_world_edit_context lists available_apps. Pass add_app: {"app": "greenhouse"} to preview an app’s collection bindings and schemas. To call edit_world directly, include {"kind": "add_app", "app": "greenhouse"} in changes_json, followed by complete add operations for its records. An optional account distinguishes accounts of the same app. A new app can initialize its own principal and workspace records in that batch. To remove an app and its bound records from the new version, include {"kind": "remove_app", "instance": "<instance-key>"}. Use the instance key returned by the context tool. The World must retain at least one app, and additions are limited to 16 app instances. Removal is unavailable for Worlds with legacy actions or shared app collections. App additions use registered simulations and their existing tool APIs. To author custom actions, use publish_world_version with a complete World definition. App changes affect new instances started from the published version.

Add more history

You can request dated synthetic records through a description. A request such as “add two months of history across all apps” must still fit the 10,000-change and 768 KiB limits. For a larger generated expansion, follow Create an expanded variation. That workflow supports a separate World or another version of the same World, within the supported apps’ generation limits.

Change records while an agent runs

Use edit_world with instance_id to change the records in the instance your agent is using. The change takes effect immediately, and subsequent agent reads see it. You can edit the instance before connecting your agent and continue during execution.
  1. Call get_world_edit_context with instance_id. Select a returned collection and use include_content: true to inspect its current records and schema.
  2. Call edit_world with the same instance_id, an idempotency_key, and explicit changes_json. Your coding agent can translate a prompt into these operations. The route’s description parameter accepts version edits only. Use dry_run: true to validate without changing records.
  3. To require the instance to remain at the step you inspected, pass its step_count as expected_step_count. If the agent advanced, inspect again and use a new key.
Replace the collection binding and record ID with values from the context tool:
One batch commits atomically as an external step. The response includes step_id, the new step_count, and the World time at. You can change records the agent previously wrote; earlier steps stay unchanged. Identical retries return the same committed step, including after the instance closes, while you retain write access. A batch that changes no records conflicts. Live edits support additions, updates, and deletions across existing app accounts, with the same schema, reference, and protected account rules as version edits. Adding or removing an app requires a new version. Each record must fit within 256 KiB and the step’s effects within 1 MiB; older inline instances also have a 256 KiB total state limit. Live edits do not schedule future changes or deliver app notifications. To act as another person, deliver a notification, or advance World time, use the instance action tools. expected_step_count checks the current step without waiting for it. To introduce a change later in a run, have your test controller call edit_world at that point. The returned at reports when the edit committed in World time.

Start from a historical time

To change historical starting data, start an instance from a World model at a represented time, then edit the returned instance before connecting your agent. You can continue editing during the run. The retained history and source version keep their original data.