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 penNameId argument. 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 its StorytellerOS id, name, genres, tagline, and heat level.
stos_pen_names_get	Full pen-name record including guides, persona, prose sample, and links. Read before drafting prose.
stos_pen_names_update	Update guides, persona, tagline, and genres. Relevant changes synchronize with Social Studio automatically.

Social Studio

Connected accounts, publishing, scheduling, delivery status, campaign drafts, and recurring queues. Every operation can be scoped to a pen name.

Tool	Description
stos_social_accounts_list	List connected social destinations.
stos_social_posts_list	List posts by status, platform, or date range.
stos_social_posts_get	Get one post and its destination configuration.
stos_social_posts_create	Create an immediate, scheduled, draft, or queued post with platform preflight.
stos_social_posts_update	Update copy, media, destinations, or schedule.
stos_social_posts_archive	Archive a post without hard deletion.
stos_social_posts_retry	Retry a failed post.
stos_social_posts_unpublish	Unpublish a supported destination post.
stos_social_posts_logs	Read destination delivery logs.
stos_social_campaigns_list	List Social Studio campaigns.
stos_social_campaigns_get	Get a campaign and its planned posts.
stos_social_campaign_drafts_list	List campaign drafts awaiting review.
stos_social_queues_list	List recurring publishing queues.
stos_social_queues_create	Create a timezone-aware recurring queue.
stos_social_queues_update	Update queue slots, destinations, status, or persona.
stos_social_queues_delete	Delete a recurring queue.
stos_social_queues_next	Get the next available queue slot.

Ads Studio

Cross-network campaign planning, creation, analytics, attribution, audiences, conversion events, AI creative work, and Amazon Sponsored Products. Spend-impacting tools require review and create paused by default.

Tool	Description
stos_ads_accounts_list	List connected ad destinations and accounts.
stos_ads_campaigns_unified	Compare normalized campaign performance across destinations.
stos_ads_create	Create an idempotent reviewed campaign plan, paused by default.
stos_ads_update	Update an ad with a stable idempotency key.
stos_ads_campaign_status_update	Pause or activate a campaign after explicit confirmation.
stos_ads_analytics	Get daily and audience-breakdown analytics for one ad.
stos_ads_recommendations	Analyze results and return review-only suggested actions.
stos_ads_optimize	Score campaigns deterministically without changing delivery.
stos_ads_lead_forms_list	List destination-native instant lead forms.
stos_ads_lead_forms_create	Create a reviewed instant lead form.
stos_ads_title_mapping_set	Map a campaign to its canonical StorytellerOS title.
stos_ads_audiences_list	List reusable destination audiences.
stos_ads_targeting_search	Search valid interests, behaviors, and locations.
stos_ads_conversion_send	Send a confirmed server-side conversion event.
stos_ads_creative_draft	Draft a campaign grounded in title and pen-name data.
stos_ads_creative_copy	Generate grounded hooks and ad copy.
stos_ads_creative_images_generate	Generate ad images into the shared creative asset feed.
stos_ads_creative_assets_list	List generated creative assets.
stos_ads_amazon_create	Create an idempotent Amazon Sponsored Products campaign, always paused.
stos_ads_amazon_campaigns	List Amazon campaign performance.
stos_ads_amazon_profitability	Compare Amazon-attributed sales, royalties, spend, ACOS, and ROAS.
stos_ads_amazon_sync	Request fresh Amazon Ads reports.

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.

Media Studio

Generate media and organize the shared StorytellerOS library. Character portraits can be used directly as generation references.

Tool	Description
stos_media_generate	Generate images, video, or audio. Pollinations is the default; pass up to three referenceUrls.
stos_media_generation_status	Poll active generation jobs and allowance status.
stos_media_assets_list	List shared assets with kind, source, folder, tag, search, and pen-name filters.
stos_media_assets_update	Replace tags, move folders, or update accessible alt text.
stos_media_assets_delete	Delete an asset and propagate deletion to its linked mirror.
stos_media_folders_list	List account-wide and pen-name media folders.
stos_media_folders_create	Create a root or nested media folder.
stos_media_folders_delete	Delete a folder while retaining its assets as unfiled.
stos_media_character_references_list	List character portraits with fresh signed URLs for referenceUrls.

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.

Email Studio (NOT social)

CRM, website tracking, forms, email design, SMTP senders, campaigns, automations, suppressions, and engagement reporting. Social work uses the stos_social_* tools.

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_contacts_import	Bulk import contacts with list/tag names.
stos_email_contacts_bulk_memberships	Bulk add/remove contacts from lists or tags.
stos_email_contacts_find_duplicates	Find duplicate email records in an audience.
stos_email_contacts_profile	Complete customer profile, engagement stats, and email/website timeline.
stos_email_contacts_merge	Merge a duplicate into a primary contact.
stos_crm_contacts_search	Search, filter, sort, and page the complete pen-name CRM table.
stos_crm_field_definitions_list	List typed CRM custom fields.
stos_crm_field_definitions_create	Create a typed CRM custom field.
stos_crm_contact_views_list	List saved contact table views.
stos_crm_contact_views_create	Save a filtered/sorted contact view.
stos_crm_segments_list	List dynamic CRM segments.
stos_crm_segments_preview	Preview a segment and its matching count.
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	Send a test, schedule delivery, or start a live SMTP broadcast.
stos_email_campaigns_preflight	Validate sender, audience, content, links, accessibility, test-send evidence, and managed cost.
stos_email_campaigns_analytics	Campaign opens, clicks, bounces, complaints, and unsubscribes.
stos_email_campaigns_delivery_report	Recipient-level delivery, engagement, retries, and failures.
stos_email_template_catalog	Browse built-in and genre-specific email templates.
stos_email_design_defaults_get	Get reusable campaign typography, color, and spacing defaults.
stos_email_design_defaults_save	Save reusable campaign design defaults.
stos_email_templates_user_list	List saved templates and reusable sections.
stos_email_signup_forms_list	List hosted, embedded, and popup signup forms.
stos_email_signup_forms_analytics	Form conversions, sources, confirmations, and A/B results.
stos_email_automations_list	List drip, welcome, date, tag, list, form, and manual automations.
stos_email_automations_enroll	Bulk enroll contacts in an automation.
stos_email_senders_list	List safe per-pen-name SMTP settings and provider presets.
stos_email_senders_save	Save encrypted SMTP credentials for one pen name.
stos_email_senders_test	Send a real SMTP test and mark the sender verified.
stos_managed_email_domains_list	List managed-domain status and StorytellerOS-branded DNS records.
stos_managed_email_domains_request	Request manual managed-domain provisioning ($3 per 10,000 emails).
stos_email_suppressions_list	List unsubscribe, bounce, complaint, manual, and provider suppressions.
stos_email_suppressions_create	Manually suppress an address.
stos_email_suppressions_reactivate	Explicitly reactivate a suppressed address.
stos_website_tracking_sites_list	List tracking sites and visitor/page/event summaries.
stos_website_tracking_sites_create	Register a consent-aware first-party tracking site.
stos_website_tracking_activity	Inspect identified visitors, page views, and custom events.

Settings & utilities

Profile, AI provider configuration, Cowork connector listing, notifications.

Tool	Description
stos_settings_profile_get	Get profile settings.
stos_settings_api_keys_get	List StorytellerOS API access-key metadata. Never returns plaintext secrets or key hashes.
stos_settings_ai_providers_get	Get AI provider connection flags and text/media defaults without returning plaintext keys.
stos_settings_ai_providers_update	Configure the shared Pollinations account, AI enablement, and text/media defaults.
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.