Skip to main content
Glama
putervision

world-model-mcp

by putervision
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

update_entity

Create a spatial entity or partially update an existing one in the world model; omit id to create, provide id to merge fields while preserving omitted values.

Instructions

Create or upsert one spatial entity (position, orientation, AABB, tags, properties, confidence). Manual authoring only. Omit id to create (ULID assigned). Provide id to update. Omitted fields are preserved; this is a partial merge, not a full replace. status defaults to active. confidence is 0.0–1.0 object-permanence. Does not ingest vision detections or apply action results. Returns {ok, entity_id, created:boolean, entity}. Use update_entity instead of ingest_observation when authoring entities directly rather than merging perception detections.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNoOptional entity ID (auto-generated ULID if omitted for creation)
nameYesHuman-readable name or label of the entity
tagsNoArray of searchable string tags
typeYesCategorical entity type
statusNoEntity lifecycle status (default: active)
projectNoOptional project identifier
positionNo3D world position coordinates
velocityNo3D velocity vector (vx, vy, vz) for physical motion and predictive permanence
parent_idNoOptional parent entity ID for hierarchical containment or attachments
region_idNoOptional named region ID where this entity resides
confidenceNoObject permanence confidence score from 0.0 to 1.0 (default: 1.0)
propertiesNoArbitrary JSON key-value properties (physics, materials, interactive state)
orientationNo3D Euler orientation angles in degrees
bounding_boxNoAABB bounding volume size
affordance_maskNoBitmask of physical interaction affordances (1=traversable, 2=occluder, 4=container, 8=interactable, 16=threat)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.0
    • addedInput schema / properties / affordance_mask
      Added value: +{
+  "description": "Bitmask of physical interaction affordances (1=traversable, 2=occluder, 4=container, 8=interactable, 16=threat)",
+  "type": "number"
+}
    • addedInput schema / properties / velocity
      Added value: +{
+  "description": "3D velocity vector (vx, vy, vz) for physical motion and predictive permanence",
+  "properties": {
+    "x": {
+      "description": "Velocity along X axis",
+      "type": "number"
+    },
+    "y": {
+      "description": "Velocity along Y axis",
+      "type": "number"
+    },
+    "z": {
+      "description": "Velocity along Z axis",
+      "type": "number"
+    }
+  },
+  "type": "object"
+}
  2. Changed6 schema fields changedv0.4.1
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties / bounding_box / additionalProperties
      Removed value: -true
    • removedInput schema / properties / orientation / additionalProperties
      Removed value: -true
    • removedInput schema / properties / position / additionalProperties
      Removed value: -true
    • removedInput schema / properties / properties / additionalProperties
      Removed value: -{}
  3. First observedv0.3.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare the generic safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), yet the description adds the semantics that actually matter: this is a partial merge that preserves omitted fields rather than a full replace, ids are ULID-assigned on create, status defaults to active, and it does not ingest vision detections or apply action results. With no output schema present, it also supplies the return shape {ok, entity_id, created, entity}.

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 verb and merge rule, and nearly every clause carries information. There is mild redundancy: 'Manual authoring only' and 'Does not ingest vision detections' partially overlap with the closing sentence routing to ingest_observation, which could be tightened to one statement.

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 15-parameter tool with nested objects and no output schema, the description covers everything an agent needs: creation vs update branching, merge vs replace semantics, defaults, the confidence scale, what the tool deliberately does not do, and the response payload. No material gap remains.

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 already 100%, so the baseline is 3. The description goes beyond it by explaining id's dual role (create vs update), the ULID auto-assignment behavior, the 0.0–1.0 object-permanence meaning of confidence, and the active default for status — semantics the schema states only as types and defaults.

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?

Opens with a specific verb pair and resource: 'Create or upsert one spatial entity', then enumerates the payload domains (position, orientation, AABB, tags, properties, confidence). It explicitly contrasts itself with the sibling ingest_observation, so an agent can route without opening either 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 concrete when-to-use rules keyed on the id parameter ('Omit id to create', 'Provide id to update'), states the scope constraint ('Manual authoring only'), and names the alternative with the discriminating condition versus ingest_observation. Nothing is left to inference.

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

Deploy Server

Other Tools