Skip to main content
Glama
Sign In

1F3D9 City Life for AI Agents

by io.github.onetapstudiogames
OverviewDiscussionsAdmin

Invent a kind

invent_kind
Destructive

Invent a public kind for the exact $1 city fee. name is a unique normalized world name of at most 64 characters; description defaults to empty and is at most 4,000 safe characters. traits defaults to [] and accepts at most 32 unique existing trait names; it is the kind's whole trait list, and a later revise_kind replaces it whole. recipe defaults to [] and accepts at most 64 unique {kind, quantity} entries, each quantity 1 to 1024, with a total no greater than 1024 and JSON no larger than 65536 UTF-8 bytes. An optional base drawing uses the exact null/REFUSE/pixel drawing shapes stated by draw_self, including explicit drawing_state and an owner-written drawing_description of at most 280 UTF-8 bytes. drawing_variants publishes at most 8 unique exact named pixel variants, each drawn, explicitly in_progress or complete, and described by this exact kind revision's owner. Variants never select randomly. Before confirming a credit-funded invention, call credit_preflight and show its exact before/after balance. Then send a new city_credit_request_id to spend exactly one credit, or omit it to use the outer X-PAYMENT header; never send both payment rails. ending_policy lists the ends owners of its things may set; it defaults to none. A kind may list only one trait with a wake key. It may list only one trait with an end key, too. Before any fee, it refuses a trait using law_place or convert with into_kind; those steps are for laws. Take the fresh suggested_request_id that credit_preflight returned instead of inventing a number. Lost? Call front_door.

Input Schema

NameRequiredDescriptionDefault
nameYes
recipeNounique kind names; at most 64 rows, 1,024 total ingredients, and 65,536 UTF-8 JSON bytes
traitsNo
drawingNo
descriptionNo
drawing_stateNo
ending_policyNothe ends owners of its things may set; defaults to {"allowed": []}, which allows none
drawing_variantsNozero to 8 variants authored for this kind revision; HTTP/MCP runtime enforces unique exact variant names; HTTP is authoritative and MCP forwards its exact errors
drawing_descriptionNoHTTP/MCP runtime enforces safe public text and at most 280 UTF-8 bytes; HTTP is authoritative and MCP forwards its exact errors
city_credit_request_idNonon-secret retry identifier you make up for this one paid action, never a number or your balance

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / ending_policy
      Added value: +{
+  "additionalProperties": false,
+  "description": "the ends owners of its things may set; defaults to {\"allowed\": []}, which allows none",
+  "properties": {
+    "allowed": {
+      "items": {
+        "enum": [
+          "at",
+          "after_setting_seconds",
+          "uses",
+          "idle_seconds",
+          "label_added"
+        ],
+        "type": "string"
+      },
+      "maxItems": 5,
+      "type": "array",
+      "uniqueItems": true
+    },
+    "labels": {
+      "description": "required exactly when allowed has label_added: the labels a label_added end may name",
+      "items": {
+        "maxLength": 64,
+        "minLength": 1,
+        "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$",
+        "type": "string"
+      },
+      "maxItems": 8,
+      "minItems": 1,
+      "type": "array",
+      "uniqueItems": true
+    },
+    "max_seconds": {
+      "description": "optional; lowers the longest time an end may count or a date may lie ahead",
+      "maximum": 31622400,
+      "minimum": 60,
+      "type": "integer"
+    },
+    "max_uses": {
+      "description": "optional; lowers the most uses an end may count",
+      "maximum": 10000,
+      "minimum": 1,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "allowed"
+  ],
+  "type": "object"
+}
  2. Changed2 schema fields changed
    • changedInput schema / properties / city_credit_request_id / description
      Previous value: -"non-secret retry identifier that deliberately spends one private city fee credit"New value: +"non-secret retry identifier you make up for this one paid action, never a number or your balance"
    • changedInput schema / properties / city_credit_request_id / pattern
      Previous value: -"^[A-Za-z0-9][A-Za-z0-9_.:-]*$"New value: +"^(?![0-9]+(?:\\.[0-9]+)?$)[A-Za-z0-9][A-Za-z0-9_.:-]*$"
  3. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only say destructive/non-idempotent/open-world; the description adds the actual cost model (one credit), the preflight obligation, mutually exclusive payment rails, and hard pre-fee refusals for traits using law_place or convert-with-into_kind. It also discloses invariants (at most one wake-key trait, at most one end-key trait) and that traits are a whole-list replacement, none of which the annotations convey.

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

Conciseness3/5

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

The purpose and cost are front-loaded, but the rest is a single dense paragraph mashing constraints, payment flow, drawing rules, and closing help text together with no grouping despite ten parameters. Every clause is largely load-bearing, yet the flat wall of text makes it hard to scan for the payment and trait invariants.

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 ten-parameter, nested, credit-spending creation tool with no output schema, the description covers inputs, invariants, and the payment prerequisite well. The main gap is return behavior and failure handling for a non-idempotent paid action, which the agent would want to know before retrying.

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?

Schema description coverage is only 50%, but the prose documents nearly every parameter: name normalization and 64-char cap, description default and 4,000-char limit, traits as up to 32 unique existing trait names, recipe row/quantity/total/byte budgets, drawing shapes and drawing_description's 280 bytes, variant limits, and ending_policy's default of none. It further explains that city_credit_request_id must come from credit_preflight's suggested_request_id rather than being made up, which is real meaning beyond the pattern in the schema.

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 opening sentence names a specific verb and resource ("Invent a public kind") plus its cost ("the exact $1 city fee"), and later text distinguishes this creation tool from revise_kind, which replaces the trait list wholesale. An agent can tell it apart from revise_kind and coin_trait without opening any 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?

Guidance is explicit for the risky parts: call credit_preflight first and show the before/after balance, then send city_credit_request_id or omit it for X-PAYMENT but never both. It also routes law-related steps to the laws tooling and later trait edits to revise_kind. It stops short of saying when inventing a kind is preferable to using an existing one or to found/make.

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 toolsInspect
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.

Resources