Worldbuilding — single entries

When to use this vs. other skills

Canonical field values — send these exactly

The Story Bible tables have strict CHECK constraints, and several columns (aliases, family_group, key_features, tags, themes, story_framework, …) are arrays. The MCP tools now enforce both in their input schema: a non-canonical enum value, or a bare string where an array is expected, is rejected immediately with a clear error listing the allowed shape — a wasted round-trip, not a silent failure. Map synonyms to the canonical value below before calling the tool; pass array columns as real JSON arrays (["a","b"]), never a comma-joined string. If a value can't be mapped, omit the field entirely — never invent, never stash the original somewhere else.

Never send custom_fields on a Cowork worldbuilding create call. The StorytellerOS UI does not render those keys for Cowork-completed records — the data lands invisible. Stick to the named columns listed in each tool's writable-fields description.

Flow for one entry

1. Resolve scope: pen name + (optionally) title or series.
2. Draft the entry in the conversation — full fields, not a stub.
3. Show it to the user for approval.
4. Save: stos_characters_create, stos_locations_create, stos_events_create, or stos_lore_create.
5. If the entry has natural associations ("she's in chapter 3"), call stos_worldbuilding_link for each.

Editing an existing entry

If you need ONE record, use _get then _update:

stos_characters_get({ id })
// review the current fields
stos_characters_update({ id, fields: { backstory: 'updated paragraph...' } })

If you need TWO OR MORE records, do NOT loop _get. Use stos_characters_get_many, stos_locations_get_many or stos_lore_get_many with { ids: [...] }: one round-trip instead of N. This matters because every MCP round-trip replays the full ~50KB tool schema; loading 10 characters via 10 separate _get calls vs. one bulk-get is the difference between 500KB and 50KB of overhead. The bulk-get tools cap at 100 ids per call. (Events don't have a bulk-get yet; for those, keep the loop small.)

Anti-patterns

• Creating a duplicate. If the user says "add Sasha to Curses and Currents", check stos_characters_list first — Sasha may already exist under another title and just need a stos_worldbuilding_link. If the user already knows there are duplicates, route them to the character-merge skill — it has a server-side duplicate finder that's dramatically cheaper than reviewing pairs in conversation.
• Saving a stub. A character record with only character_name is technically valid but useless. Draft the full record before saving.
• Looping _get to compare multiple records. Use the _get_many tools for 2 or more characters, locations or lore entries. For dedup work, use character-merge or worldbuilding-merge.
• Sending non-canonical enum values, or a string for an array column. The tool input schema rejects both with an explicit error — map enum synonyms first (see the table above), and pass array columns as JSON arrays.