Tools reference

Every stos_* MCP tool the plugin exposes. Each one wraps a /api/v1/* endpoint so the two transports share one implementation.

How to read this

Tools come in five common shapes: _list, _get, _create, _update, _delete. Updates are PATCH semantics — pass only the fields you want changed. Resources that have extra workflow (timers, set-active, send, complete) get bespoke additional tools listed in the right group.

_list tools return a light projection of the first 50 rows by default. Pass fields:"full" for every column (or use _get for one full record), limit/offset (or limit:"all") to page, and count:true for a bare { count } with no rows. For account-wide orientation, prefer stos_account_manifest / stos_email_overview / stos_sales_overview over many separate _list calls.

Every scoped tool accepts an optional penNameIdargument. Pass it on every call in a multi-step flow — it doesn't carry across automatically. Without one, calls target your active / primary pen name.

Discovery & scope

Always call these first when the user mentions a specific pen name — the penNameId argument is required on every scoped tool downstream.

Tool	Description
stos_account_manifest	One-call orientation: the whole pen-name → series → title catalog with chapter/scene + worldbuilding counts, light projection. Call this instead of stos_pen_names_list + stos_series_list + stos_titles_list. depth: pen_names\|series\|titles\|full.
stos_pen_names_list	List every pen name. Returns id, name, genres, tagline, heat_level, and (when synced) the aaProfileId used for the social hand-off.
stos_pen_names_get	Full pen-name record — guides, persona, prose_sample, links, AA-sync state. Read before drafting prose.
stos_pen_names_update	Update guides / persona / tagline / genres. Changes to name or detailed_bio fan out to Author Automations automatically.

Writing Studio

Titles, chapters, scenes, and multi-revision manuscript files. The DB column is still books for legacy reasons; the API and tools say "title".

Tool	Description
stos_titles_list	List titles. Filter by seriesId, status.
stos_titles_get	Full title record + retailer listings.
stos_titles_create	Create a title. Required: title (string).
stos_titles_update	PATCH semantics — only the fields you pass.
stos_titles_delete	Delete a title and its cascaded children.
stos_chapters_list	List chapters. Filter by bookId.
stos_chapters_get	Full chapter record.
stos_chapters_create	Create a chapter under a title.
stos_chapters_update	Update chapter title, content path, status.
stos_chapters_delete	Delete a chapter.
stos_scenes_list	List scenes. Filter by bookId / chapterId.
stos_scenes_get	Full scene record.
stos_scenes_create	Create a scene under a chapter.
stos_scenes_update	Update scene fields.
stos_scenes_delete	Delete a scene.
stos_title_manuscripts_list	List manuscript file revisions for a title.
stos_title_manuscripts_create	Register an already-uploaded manuscript as a new revision (caller uploads via the dashboard or presigned URL).
stos_title_manuscripts_update	Rename or annotate a revision.
stos_title_manuscripts_delete	Remove the revision record. The underlying storage file is preserved for recovery.
stos_title_manuscripts_set_active	Mark a revision as active for its title (mirrors storage_path onto books.word_doc_storage_path).

Knowledge Studio

The story bible — characters, locations, lore, story-timeline events, notes, and personal documents. Plus the worldbuilding-links dispatcher for junction tables.

Tool	Description
stos_characters_list	List characters. Filter by seriesId.
stos_characters_get	Full character record.
stos_characters_create	Create a character. Required: character_name. All depth fields (core_desire, core_fear, character_arc, etc.) writable.
stos_characters_update	Patch any writable column.
stos_characters_delete	Delete a character.
stos_locations_list	List locations.
stos_locations_get	Full location record.
stos_locations_create	Create a location. Required: location_name. Fields include description, type, key_features, climate, coordinates, map_image_url.
stos_locations_update	Patch any writable column.
stos_locations_delete	Delete a location.
stos_lore_list	List lore entries.
stos_lore_get	Full lore record.
stos_lore_create	Create a lore entry. Required: lore_name. Fields: type, rules_and_mechanics, examples_and_usage, origin_and_history, contradictions_check, tags.
stos_lore_update	Patch any writable column.
stos_lore_delete	Delete a lore entry.
stos_events_list	List story-timeline events (NOT user-calendar — see calendar tools).
stos_events_get	Full story-event record.
stos_events_create	Create a story-timeline event. event_date is free text (in-universe dates may not match real calendars).
stos_events_update	Patch any writable column.
stos_events_delete	Delete a story event.
stos_notes_list	List chapter sticky notes.
stos_notes_get	Full note record.
stos_notes_create	Create a note scoped to a chapter.
stos_notes_update	Edit a note.
stos_notes_delete	Delete a note.
stos_personal_documents_list	List user personal documents.
stos_personal_documents_get	Full document record.
stos_personal_documents_create	Create a personal document.
stos_personal_documents_update	Update a document.
stos_personal_documents_delete	Delete a document.
stos_worldbuilding_link	Create one association between a writing-studio entity (title/chapter/scene/series/event/lore) and a knowledge-studio entity (character/location/event/lore). Single-pair only — never batched.
stos_worldbuilding_unlink	Remove an association. Same body shape as _link.

Series

Multi-book series grouping. Owns its own worldbuilding (themes, framework, supernatural mechanics).

Tool	Description
stos_series_list	List series. Filter by penNameId.
stos_series_get	Full series record.
stos_series_create	Create a series. Required: series_name.
stos_series_update	Patch any writable column.
stos_series_delete	Delete a series.

Tasks

Multi-pen-name task list. Filter by status, priority, scope.

Tool	Description
stos_tasks_list	List tasks. Filter by status, bookId, seriesId, item_type.
stos_tasks_get	Full task record.
stos_tasks_create	Create a task. Required: task_name. Priority: high\|medium\|low. Status: to-do\|in-progress\|completed.
stos_tasks_update	Patch any writable column.
stos_tasks_delete	Delete a task.
stos_tasks_complete	Sugar — PATCH with status=completed.

Calendar (user)

Real-world calendar events — release dates, signings, deadlines. Separate from story-timeline events.

Tool	Description
stos_calendars_list	List user calendars.
stos_calendars_create	Create a calendar.
stos_calendars_update	Patch any writable column.
stos_calendars_delete	Delete a calendar.
stos_calendar_events_list	List calendar events. Filter by calendarId, from, to (ISO dates).
stos_calendar_events_get	Full calendar event.
stos_calendar_events_create	Create an event on a calendar.
stos_calendar_events_update	Patch any writable column.
stos_calendar_events_delete	Delete an event.

Time tracking

Timed work blocks, writing sessions, writing goals, pomodoro settings.

Tool	Description
stos_time_tracking_list	List time-tracking entries.
stos_time_tracking_get	Full entry.
stos_time_tracking_create	Create an entry directly (e.g. retroactive logging).
stos_time_tracking_update	Patch any writable column.
stos_time_tracking_delete	Delete an entry.
stos_time_tracking_start	Start a timer now. Provide one or more of penNameId / bookId / chapterId for attribution.
stos_time_tracking_stop	Stop an active timer (sets ended_at = now).
stos_writing_sessions_list	List writing sessions.
stos_writing_sessions_create	Create a writing session.
stos_writing_sessions_update	Update a session.
stos_writing_sessions_delete	Delete a session.
stos_writing_goals_list	List writing goals.
stos_writing_goals_create	Create a writing goal.
stos_writing_goals_update	Update a goal.
stos_writing_goals_delete	Delete a goal.
stos_pomodoro_settings_get	Get pomodoro defaults.
stos_pomodoro_settings_update	Update pomodoro defaults.

Finance

Vendors + income/expense transactions + summaries. Strips developer jargon from user-facing surfaces.

Tool	Description
stos_vendors_list	List vendors.
stos_vendors_get	Full vendor record.
stos_vendors_create	Create a vendor. Required: vendorName. Fields: type, email, phone, website, address, notes.
stos_vendors_update	Patch any writable column.
stos_vendors_delete	Delete a vendor.
stos_finance_transactions_list	List income/expense transactions. Filter by transactionType, bookId, seriesId, vendorId.
stos_finance_transactions_get	Full transaction.
stos_finance_transactions_create	Create a transaction. Required: transactionName, transactionType (income\|expense), amount, transactionDate, category.
stos_finance_transactions_update	Patch any writable column.
stos_finance_transactions_delete	Delete a transaction.
stos_finance_summary	Aggregated totals over a date range — income, expense, net, plus per-group breakdowns. Range: month\|quarter\|ytd\|year\|all. groupBy: category\|book\|vendor\|pen_name\|type.

Sales Studio

Retailers, retailer links, title variations, marketing assets, products, reviews.

Tool	Description
stos_retailers_list	List retailers (Amazon, Kobo, Apple Books, etc.).
stos_retailers_get	Full retailer record.
stos_retailers_create	Add a new retailer.
stos_retailers_update	Update a retailer.
stos_retailers_delete	Delete a retailer.
stos_retailer_links_list	List retailer links. Filter by titleVariationId, retailerId.
stos_retailer_links_create	Create a link tying a variation to a retailer.
stos_retailer_links_update	Update sales metadata / URL.
stos_retailer_links_delete	Delete a retailer link.
stos_title_variations_list	List variations (ebook / paperback / audiobook / etc.). Filter by titleId.
stos_title_variations_create	Create a variation under a title.
stos_title_variations_update	Update ASIN/ISBN/blurb/cover URLs.
stos_title_variations_delete	Delete a variation.
stos_title_marketing_assets_list	List marketing assets. Filter by titleId.
stos_title_marketing_assets_create	Create a marketing asset.
stos_title_marketing_assets_update	Update content / file URLs.
stos_title_marketing_assets_delete	Delete an asset.
stos_products_list	List storefront products.
stos_products_get	Full product record.
stos_products_create	Create a product.
stos_products_update	Update a product.
stos_products_delete	Delete a product.
stos_reviews_list	List reviews.
stos_reviews_get	Full review record.
stos_reviews_create	Log a review.
stos_reviews_update	Update a review.
stos_reviews_delete	Delete a review.
stos_sales_overview	One-call sales orientation: variation counts (by status), retailer + retailer-link counts, review total + average rating, and an income/expense/net rollup. Cheap (counts, no rows). penNameId scopes the finance rollup.

Marketing Studio (NOT social)

Email + articles + FAQs + webinars. Social work routes through the Author Automations plugin instead.

Tool	Description
stos_email_overview	One-call email orientation: contact total, list/tag counts, and automation/campaign/signup-form totals with per-status breakdowns. Cheap (counts, no rows). penNameId scopes the pen-name-aware tables; contacts are account-wide.
stos_email_contacts_list	List subscribers.
stos_email_contacts_create	Add a subscriber.
stos_email_contacts_update	Update a subscriber.
stos_email_contacts_delete	Remove a subscriber.
stos_email_lists_list	List email lists.
stos_email_lists_create	Create a list.
stos_email_lists_update	Update a list.
stos_email_lists_delete	Delete a list.
stos_email_tags_list	List email tags.
stos_email_tags_create	Create a tag.
stos_email_tags_update	Update a tag.
stos_email_tags_delete	Delete a tag.
stos_email_campaigns_list	List email campaigns.
stos_email_campaigns_get	Full campaign record.
stos_email_campaigns_create	Create a campaign draft.
stos_email_campaigns_update	Update a campaign.
stos_email_campaigns_delete	Delete a campaign.
stos_email_campaigns_send	Trigger send/schedule. Currently returns 503 while the platform-side send engine is still in stub status.

Settings & utilities

Profile, AI provider keys (presence flags only), Cowork connector listing, notifications.

Tool	Description
stos_settings_profile_get	Get profile settings.
stos_settings_api_keys_get	Get presence flags for AI provider keys (anthropic/openai/gemini/freepik/social). Never returns plaintext.
stos_oauth_clients_list	List the caller's Claude Cowork connector credential pairs (id, name, last_used_at, active flag). Plaintext secret never returned.
stos_notifications_list	List in-app notifications.
stos_notifications_mark_read	Mark a notification as read.