MCP tool reference

This is the technical companion to the MCP tools overview. It covers how the tools are called: the two connection routes, which tools an agent sees, each tool’s parameters and response shape, and the cross-cutting rules (slugs, pagination, batching).

You never invoke these by name — you describe what you want to a connected AI tool and it picks and parameterizes the calls. This page documents what it’s working with.

Two connection routes

How a world is selected depends on how the tool connected:

• Single-world (API key). An API key is bound to one world by the connection URL itself. The world is fixed for the whole session, so tools never take a world_id argument — every call operates on that one world.
• Connector (sign-in). The connector registers a single MCP URL and signs you in. World selection happens at runtime: the agent calls list_my_worlds, then set_active_world, and subsequent calls run against the active world until it switches.

Which tools an agent sees

The tool list is filtered to the connection’s access, so an agent never sees a tool it can’t use:

Access	Sees
Read-only (viewer, or read-only key)	The session, reading, search, and validation tools.
Read-write (owner/editor, or read-write key)	All of the above plus the authoring and relationship tools.
Connector only	The world-switching tools, on top of whichever of the above its role grants.

manage_entity_lore is visible to everyone, but on a read-only connection its action is limited to read.

Entity references

Wherever a tool takes or returns an entity, it’s by slug (person/john_smith, place/riverside_cafe) — never an internal ID. See Entity IDs.

Session and bootstrap

Tool	Parameters	Returns
get_world_context	entity_type?, include_stats?	The world’s schema: entity_types (with property schemas), valid_relationships, semantic_predicates, enumerations, and optional stats. Called once at the start of a session.
get_world_instructions	(none)	The world prompt — the owner’s standing rules and conventions. Called at session start and re-read if guidance may have changed.

Switching worlds (connector only)

Tool	Parameters	Returns
list_my_worlds	filter? (in_grant_only, search), cursor?	The worlds you can reach, in-grant ones first, each annotated with whether this app currently has access.
set_active_world	world_id	Activates a world for the session after access and role checks.

Reading and searching (read-only)

Tool	Parameters	Returns
get_entities	entity_ids (1–20), view (compact|full), active_only?, relationships?, lore?	Full records for specific entities, with paginated relationships and lore blocks. view: "compact" returns block counts only.
search_entities	query?, entity_type?, tags?, filter?, view?, limit?, cursor?, return?	Paginated entity hits (return: "entities") or the tag aggregation (return: "tags"). filter is a single property predicate (e.g. a date range or status check).
query_relationships	mode (edges|neighbors), plus mode-specific filters	edges: matching relationships by source/target/type. neighbors: an entity’s relationship neighbourhood, 1–3 hops out. Active edges by default; active_only: false includes history.
get_timeline	start_year?, end_year?, event_types?, location_id?, …	Events in chronological order.
search_lore	query, entity_id?, entity_type?, limit?	Semantic search across lore, ranked by similarity.
audit_world	entity_id?, check_types?, severity?, strict_mode?, limit?, cursor?	Consistency issues — world-scope (omit entity_id) or entity-scope. Issues carry a severity of error, warning, or info.

Authoring content (read-write)

Tool	Parameters	Returns
create_entities	entities (1–100), skip_existing?	{ created, skipped, counts }. Creating one entity is just the N=1 case.
update_entity	entity_id, updates, merge_mode? (replace|merge)	The updated fields and timestamp.
delete_entity	entity_id, cascade?, reason?	Confirmation, plus how many relationships were removed.
manage_entity_lore	action (create|read|update|delete), entity_id, lore_id?, title?, content?	Result of the lore operation. Read-only connections get read only.
add_enumeration_term	entity_type, property, value, description?	Registers a new standard value in a property’s enumeration.

Relationships (read-write)

Tool	Parameters	Returns
create_relationships	relationships (1–100, each source_id / target_id / relationship_type / properties? / started? / ended?), skip_duplicates?	{ created, skipped, counts }.
update_relationship	relationship_id, updates?, started?, ended?	Set ended to mark a relationship historical; clear it to reactivate one.
delete_relationship	relationship_id	Confirmation. Prefer setting ended over deleting — reserve deletion for genuine mistakes.

Batching

create_entities and create_relationships each accept 1 to 100 items in a single call, so an agent can stand up a chunk of the graph at once. skip_existing / skip_duplicates make a batch tolerant of items that already exist — they’re reported as skipped instead of failing the whole call.

Pagination

Result-bearing reads (get_entities blocks, search_entities, query_relationships, audit_world) return a next_cursor when more results remain. The cursor is opaque and bound to the filters of the request that produced it — when fetching the next page, re-send the identical filters. Changing a filter mid-pagination invalidates the cursor and the call is rejected, rather than silently returning a mismatched slice.

Usage patterns

A well-behaved agent tends to:

1. Call get_world_context and get_world_instructions once, up front.
2. Search before creating — check for an existing entity before adding one, to avoid duplicates.
3. Triage cheaply with search_entities (view: "compact"), then get_entities on the few worth a full read.
4. Author in batches, then connect with create_relationships.
5. Mark relationships historical with ended rather than deleting them.

---

If an agent reports a tool is unavailable, the connection probably lacks the permission, or — on the connector — no world is active yet. See Troubleshooting.