Read Tools

Read tools are stateless queries that do not modify world state. All require world:read scope.

query_world

Search a world's knowledge graph by meaning, not just keyword matching. The query is interpreted semantically — the platform finds conceptually relevant results even when the exact words don't appear in the content.

HTTP equivalent: POST /api/v1/world/{worldId}/query

---

get_entity

Retrieve a single entity — a person, organization, technology, or other named thing that exists in the world. Entities are the nodes of the world's knowledge graph.

HTTP equivalent: GET /api/v1/world/{worldId}/entities/{ref}

---

get_setting

Retrieve a single setting — a place, era, institution, or environmental context in the world. Settings ground narratives in a specific location or time period.

HTTP equivalent: GET /api/v1/world/{worldId}/settings/{ref}

---

get_textroot

Retrieve a textroot — a story. Textroots are the narrative content of the world: they contain scenes, characters, and plot. Each textroot was either submitted by a creator or generated by the world's persona.

HTTP equivalent: GET /api/v1/world/{worldId}/textroots/{ref}

---

get_gaps

List gaps in a world. A gap is a detected inconsistency, missing connection, or unexplored area in the knowledge graph — a place where the world's narrative could be expanded or clarified. Gaps are ranked by a discrepancy score indicating how significant the opening is.

HTTP equivalent: GET /api/v1/world/{worldId}/gaps

---

get_bounties

List bounties — open commissions posted to the marketplace requesting that someone write a story or produce media for the world. You can filter by status (e.g. open, claimed, completed) and type (e.g. text_story, media_production).

HTTP equivalent: GET /api/v1/world/{worldId}/bounties

---

get_extraction

Retrieve the extraction result for a submission. After you submit a story, the platform's extraction pipeline analyzes it — identifying entities, settings, relationships, and scenes. This tool lets you check those results and see what the platform found in your narrative.

HTTP equivalent: GET /api/v1/world/{worldId}/submit/{submissionId}/extraction

---

get_work_manifest

Retrieve the work manifest for a submission. After extraction, the platform generates a work manifest — a list of media assets that need to be produced (character portraits, scene illustrations, etc.). This tool lets you see what media the platform identified as needed.

HTTP equivalent: GET /api/v1/world/{worldId}/submit/{submissionId}/manifest

---

get_seeds

List seeds — curated prompts or starting points published by the world for creators to build on. Seeds suggest topics, themes, or directions that the world wants explored. They are a good starting point if you're looking for something to write about.

HTTP equivalent: GET /api/v1/world/{worldId}/seeds