MCP tools
When an AI tool connects to your world, it discovers the available MCP tools automatically — names, descriptions, and parameters all arrive over the connection itself, and clients are notified when the set changes. You don’t invoke tools by name: describe what you want in plain language and the agent picks the right calls.
Which tools an agent sees depends on its access:
- Read-only connections see only the reading and search tools.
- Read-write connections (a read-write API key, or a read-write sign-in) also see the authoring tools. On the connector they are listed for every world, and a change on a world where you are a viewer is refused when the agent tries it.
- On the connector, the agent also sees
list_my_worldsandset_active_world, and every world tool accepts aworld_id. The ID is optional when the app is granted one world or a default world is set. On a single-world URL the world is in the address, so no tool takes one and neither connector tool is present. update_world_instructionsis for the world owner, and for editors when the owner has allowed editors to edit the world instructions. Other connections cannot use it.
What’s available today
Section titled “What’s available today”The exact set evolves with Orbismo — the list your agent discovers on connection is always authoritative — but it covers:
| Tools | |
|---|---|
| Finding a world (connector only) | list_my_worlds. Returns your worlds with their ID, name, description, entity count, and your role, and marks which ones this app is granted. Agents call it first. set_active_world stores a default world for calls that omit world_id; see Choosing a world. |
| Orientation | get_world_context (the world’s schema), get_world_instructions (the world instructions). Agents call these before working in a world. |
| World instructions (owner; editors when allowed) | update_world_instructions — lets the agent write or revise the world instructions for you. |
| Reading and search | search_entities, get_entities, get_entity_lore, query_relationships, get_timeline, search_lore (semantic), audit_world (consistency checks). |
| Authoring (read-write) | create_entities, update_entity, delete_entity. |
| Lore (read-write) | create_entity_lore, update_entity_lore, delete_entity_lore — lore lives on an entity as titled chunks, each authored and edited on its own. |
| Relationships (read-write) | create_relationships, update_relationship, delete_relationship. |
A few durable conventions. Entities are referenced by slug (person/john_smith). On the connector, every world tool accepts a world_id, which is the UUID returned by list_my_worlds and never the world’s name. A call that omits it runs against the default world, and that default is the only thing the connector remembers between calls. The create tools accept up to 100 items in a single call. Paginated reads return a cursor that must be re-sent with the same filters that produced it. update_entity_lore replaces a chunk’s content wholesale rather than patching it, so agents read the chunk first, then send the full revised text.
Query behavior worth knowing
Section titled “Query behavior worth knowing”When an agent’s search returns less than you expect, it’s usually one of these:
- Property filters compare as text by default. Date and number fields need an explicit cast, and values that can’t be cast (
"end of summer"as a date) are skipped silently rather than erroring. Store dates as ISO and numbers as bare digits — and put those rules in your world instructions so every agent applies them. - One property filter per search, no
OR. For a date window,get_timelinehas native bounds; for questions that span connections, traverse withquery_relationshipsand narrow from there. A missing property never matches a comparison. search_lorematches by meaning, scoped by entity type or a single entity — not by tags.
For ready-made worlds that put these tools to work — starter templates, installable mini apps, and creative ways to use Orbismo — see the Orbismo Playbook.
If an agent says a tool isn’t available, its connection probably doesn’t have the right permission. If it says it can’t reach a world, the world may not be in the app’s grant, or the agent may have passed the world’s name instead of its ID. See Troubleshooting.