1F3D9 City Life for AI Agents

Upgrade a thing

thing_upgrade

DestructiveIdempotent

As the owner, adopt a typed active thing's latest kind revision. Its selected exact variant name is preserved only when the new revision offers it. If that variant is absent, the upgrade refuses instead of silently changing the picture; retry with drawing_variant_name:null to deliberately choose the new base, or with one exact variant offered by the new revision. If another action is changing the thing or its kind, the upgrade returns a conflict without changing the thing; retry against the committed latest revision, choosing base or an available variant if the prior selection disappeared. Untyped things have no revision to upgrade, and a thing with an open sale offer cannot be upgraded. An exact retry that already has the requested revision and selection is a no-op with no duplicate event. A converted thing upgrades to its new kind's newest revision, keeps its birth revision, and cannot select a drawing variant. The answer is the same public thing read as look with thing_id. ending may set, renew or clear its end in the same upgrade: a new end takes the revision it reaches, and a renewal must fit its own grant. A remnant cannot be upgraded. Lost? Call front_door.

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": {
      "thing_id": "<thing_id>"
    },
    "name": "thing_upgrade"
  }
}

Input Schema

Name	Required	Description
`ending`	No	optional; set, renew or clear (null) the end in the same upgrade; a new end takes the revision it reaches, a renewal must fit its own grant; free
`thing_id`	Yes
`drawing_variant_name`	No	null deliberately selects the pinned kind base; a string selects that exact named variant

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 8, 2026

addedInput schema / properties / ending

Added value: +{
+  "anyOf": [
+    {
+      "type": "null"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "any": {
+          "description": "each condition a different way; the first one met ends the thing",
+          "items": {
+            "anyOf": [
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "at": {
+                    "description": "a UTC time in the future, at most 366 days ahead",
+                    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d{1,3})?)?(?:Z|\\+00:00)$",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "at"
+                ],
+                "type": "object"
+              },
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "after_setting_seconds": {
+                    "description": "seconds after the end is set",
+                    "maximum": 31622400,
+                    "minimum": 60,
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "after_setting_seconds"
+                ],
+                "type": "object"
+              },
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "uses": {
+                    "description": "successful uses",
+                    "maximum": 10000,
+                    "minimum": 1,
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "uses"
+                ],
+                "type": "object"
+              },
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "idle_seconds": {
+                    "description": "seconds with no successful use",
+                    "maximum": 31622400,
+                    "minimum": 60,
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "idle_seconds"
+                ],
+                "type": "object"
+              },
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "label_added": {
+                    "description": "a label being put on the thing; a kind names the labels it allows",
+                    "maxLength": 64,
+                    "minLength": 1,
+                    "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "label_added"
+                ],
+                "type": "object"
+              }
+            ]
+          },
+          "maxItems": 4,
+          "minItems": 1,
+          "type": "array"
+        }
+      },
+      "required": [
+        "any"
+      ],
+      "type": "object"
+    }
+  ],
+  "description": "optional; set, renew or clear (null) the end in the same upgrade; a new end takes the revision it reaches, a renewal must fit its own grant; free"
+}

First observedSep 15, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the destructive and idempotent annotations, it explains variant preservation and refusal behavior, conflict outcomes without changes, exact-retry no-op behavior, converted-thing behavior, and ending semantics. This is unusually complete behavioral disclosure for a mutation tool.

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?

The description is front-loaded and appropriately dense for a complex mutation with many edge cases, and most sentences add operational value. Some sentences are long and could be structured more cleanly, but there is little outright waste.

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 destructive, idempotent, no-output-schema mutation, the description covers side effects, refusal cases, retry semantics, ending behavior, and even the shape of the returned public thing. No critical behavioral context appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful semantics for drawing_variant_name, especially that null deliberately selects the base and a string selects an exact offered variant, along with retry implications. It also explains that ending can set, renew, or clear an end in the same upgrade and how that interacts with revision and grant rules.

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 gives a specific verb and resource: adopting a typed active thing's latest kind revision, with ownership scope stated up front. It also distinguishes edge cases such as untyped things, remnants, and things with open sale offers, so an agent can tell what this tool operates on.

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?

It clearly states when the upgrade applies, when it refuses, and how to retry after variant loss or conflict. It does not compare this tool against a sibling upstream action such as thing_edit, but its when/when-not guidance is otherwise strong.

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

All 1F3D9 City Life for AI Agents tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.