# Narrareach MCP tool reference Use these tools through your authorized Narrareach MCP connection. Your client receives the exact input schemas when it connects; use those schemas for field types, choices, and limits. - Connector URL: https://www.narrareach.com/mcp - Setup guide: https://www.narrareach.com/api-docs - REST contract: https://www.narrareach.com/openapi.json ## Agent rules 1. Use `list_workspaces` before acting for another writer or when the target workspace is ambiguous. 2. Read the relevant draft, Note, or schedule before changing it. 3. Ask for confirmation before scheduling, replying, archiving, cancelling, or otherwise changing user data. 4. Preserve returned identifiers and URLs so status, reschedule, and cancellation calls target the accepted item. 5. After a timeout, check the correct content list below before retrying. Do not assume an empty article list means a Note was not scheduled. 6. Treat advisories as status information unless the response explicitly says the operation failed. ## Choose the account Call `list_workspaces` to see the teams and writers you can access. Team access is supported by `list_notes`, `get_note`, `schedule_note`, `list_scheduled_items` (Notes only), `list_linkedin_destinations`, and `get_stats_insights`. The per-tool account selection below tells you which selectors to send. Drafts, article scheduling, and schedule changes currently use your personal account. For a team Note, keep the same workspace when listing, reading, and scheduling. Use a writer returned by `list_workspaces` when selecting another writer. If the account or writer is unclear, ask the user. Never switch to personal publishing to work around a team access error. ## Check the right content | Content | Find it | Read its current state | | --- | --- | --- | | Notes and social posts | `list_notes` | `get_note` with its returned `id`; retain `workspace` for team content | | Articles | `list_scheduled_posts` | Find the returned schedule `id` in that list; use `from`, `to`, and `status` filters as needed | For personal-account schedules, use `reschedule_scheduled_item` or `cancel_scheduled_item` with the returned schedule id and `kind: "note"` or `kind: "article"`. A draft id is not a schedule id. These mutation tools do not currently accept team selectors. If a team Note needs changing, use the team workspace in the Narrareach dashboard instead. An absent result is not proof that a timed-out request failed: check the correct account, filters, and list limit. If you cannot determine whether the item exists, ask the user to check Narrareach before submitting again. ## Edit scheduled LinkedIn posts with ChatGPT or another MCP assistant 1. Find the post with `list_scheduled_items` and inspect it with `get_scheduled_item_readiness` using its schedule id and `kind: "note"`. 2. Read the exact queued text with `get_note` using that same id. 3. Call `amend_scheduled_note_content` with `id`, the readiness `revision` as `expectedRevision`, and the full replacement `content`. Omit `apply` to preview without changing the post. 4. Show the preview to the user. After confirmation, repeat with `apply: true`. If the item changed, read it again and request a new confirmation. This edits only text-only LinkedIn posts in your personal account before publishing starts. It does not edit posts with media, published posts, or scheduled articles. For timing changes, use `amend_scheduled_item` with the same preview-and-confirm process. For articles, readiness returns a `draftId` for `get_draft`. That body is your Narrareach draft, not a verified copy of the article scheduled on the publishing platform. `update_draft` can change an unscheduled draft's title, body, or cover; it cannot edit an active article schedule. Cover-only changes keep the existing body and subscribe controls. Do not cancel and recreate a schedule without the user's approval. ## Getting new tools in an existing MCP connection Backend fixes to existing tools take effect after deployment. New tools appear when your client refreshes its available actions; updating these docs does not refresh a client's tool list. Keep using the same Narrareach MCP URL. For a ChatGPT developer-mode connection, open the connection, select Refresh, check the tool list, and start a new conversation. Workspace-managed apps may also require an administrator to review and enable new actions. Other MCP clients have their own refresh or reconnect controls. A missing tool alone is not a reason to disconnect LinkedIn or another publishing account. See [OpenAI's connection and refresh guide](https://developers.openai.com/plugins/deploy/connect-chatgpt#refresh-metadata). ## Field examples - **Save a draft:** `create_draft` with `{"title":"Weekly update","contentHtml":"

Approved article body.

"}`. The returned `id` is used by `get_draft`, `update_draft`, and `archive_draft`. - **Read a Note:** `get_note` with `{"id":"note_id"}`; add `workspace` only for a team Note. - **Upload an image:** `upload_media` with `{"kind":"image","sourceType":"base64","data":"BASE64_IMAGE_BYTES","mimeType":"image/png"}`. Replace the example bytes; use `kind: "video"` and the matching MIME type for video. Keep the returned `publicUrl`. - **Prepare pilot inspiration:** call `get_benchmark_inspiration` without arguments, then send the selected `recordId` and the writer's `niche` to `prepare_benchmark_inspiration`. For `schedule_note`, supply approved `content` or a suitable saved `draftId`, plus `platforms` and `scheduledFor`. For `schedule_article`, supply a saved `draftId` or new `title` and `contentHtml`, plus `platforms` and a schedule through `scheduledFor` or `platformSchedules`. Schema-required fields are listed below; these content and timing choices are also needed to schedule successfully. MCP scheduling and rescheduling use the user's local wall-clock time with an IANA `timezone`, for example `scheduledFor: "2026-12-01T09:00:00"` and `timezone: "America/New_York"`. Do not convert it to UTC yourself. The REST API has a separate timestamp contract in OpenAPI. Uploaded media uses a structured object, not an arbitrary attachment id; follow the client's media schema. ## Workspace ### `list_workspaces` List the personal account and authorized team workspaces, writers, and publications. - **Use it when:** Call before acting for another writer or when the user has more than one workspace. - **Access:** Authenticated Narrareach MCP connection. - **Account selection:** Uses your signed-in account to discover available context; no selectors needed. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** None - **Conditional fields:** None - **Returns:** Authorized workspace choices and the writer identities available in each workspace. ### `get_user_profile` Read the current user profile, plan, timezone, connection status, and available publishing context. - **Use it when:** Use at the start of a workflow that depends on timezone, plan access, or connected platforms. - **Access:** Authenticated Narrareach MCP connection. - **Account selection:** Uses your signed-in account to discover available context; no selectors needed. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** None - **Conditional fields:** None - **Returns:** Profile context and user-visible integration readiness. ## Drafts ### `list_drafts` Find drafts in your personal account by title or status. - **Use it when:** Use when the user wants to find an existing draft before reading or editing it. - **Access:** Authenticated personal account. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** `limit`, `status`, `query` - **Conditional fields:** None - **Returns:** Draft identifiers, titles, status, previews, and timestamps. ### `get_draft` Read the complete content and metadata for one authorized draft. - **Use it when:** Use after list_drafts or when the user supplies a Narrareach draft identifier. - **Access:** Authenticated personal account; the draft must belong to you. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** No. - **Required fields:** `id` - **Accepted fields:** `id` - **Conditional fields:** None - **Returns:** The draft content and public editing metadata. ### `create_draft` Save an article draft in your personal account without scheduling it. - **Use it when:** Use when the user wants content saved for review rather than published or scheduled. - **Access:** Authenticated personal account. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `title` - **Accepted fields:** `title`, `contentHtml` - **Conditional fields:** None - **Returns:** The draft id, title, and creation timestamp. Omit contentHtml only to create an empty draft. ### `update_draft` Update the title, body, or cover image of an unscheduled article draft. - **Use it when:** Use after the user asks to revise or attach media to an existing draft. - **Access:** Authenticated personal account; the draft must belong to you. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `id` - **Accepted fields:** `id`, `title`, `contentHtml`, `coverImage` - **Conditional fields:** None - **Returns:** The updated draft summary. Only supplied fields are changed. Cover-only edits preserve the existing body and subscribe controls. Active article schedules must be handled before editing the draft; this tool does not change a scheduled copy on another platform. ### `archive_draft` Archive an owned draft after active schedules have been handled. - **Use it when:** Use only after the user clearly asks to archive a draft. - **Access:** Authenticated personal account; the draft must belong to you. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `id` - **Accepted fields:** `id` - **Conditional fields:** None - **Returns:** Archive confirmation or a public recovery instruction when the draft is still scheduled. ## Notes ### `list_notes` Find scheduled, published, or failed Notes and social posts. - **Use it when:** Use to locate a Note or review recent short-form publishing work. - **Access:** Personal account or an authorized team workspace. - **Account selection:** Personal account by default; pass workspace for an authorized team workspace. Pass writer with workspace to select a team writer. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** `limit`, `status`, `platform`, `query`, `workspace`, `writer` - **Conditional fields:** None - **Returns:** Note identifiers, content summaries, destinations, and current states. ### `get_note` Read one authorized Note and its destination state. - **Use it when:** Use when the user supplies a Note identifier or selects one from list_notes. - **Access:** Personal account or an authorized team workspace. - **Account selection:** Personal account by default; pass workspace for an authorized team workspace. This tool does not accept writer. - **Changes data:** No. - **Required fields:** `id` - **Accepted fields:** `id`, `workspace` - **Conditional fields:** None - **Returns:** Note content, schedule, destination, and public status information. ### `schedule_note` Schedule short-form content to supported connected publishing destinations. - **Use it when:** Use after the user approves the content, destinations, and schedule. - **Access:** Eligible plan plus write access to every selected destination. - **Account selection:** Personal account by default; pass workspace for an authorized team workspace. Pass writer with workspace to select a team writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `scheduledFor`, `platforms` - **Accepted fields:** `draftId`, `title`, `content`, `scheduledFor`, `timezone`, `platforms`, `instagramDestinations`, `linkedInAccountId`, `linkedInOrganizationUrn`, `workspace`, `writer`, `publication`, `confirmProfileDestination`, `substackConnectionId`, `imageUrls`, `videoUrls`, `threadsTopicTag`, `firstReply`, `platformVersions`, `media` - **Conditional fields:** `postingAs`: Available only when your connected tool schema includes it. Select a connected Substack pen name, profile handle, or publication label. Use postingAs or publication, not both. This field does not grant access to another account. - **Returns:** Accepted schedule records, Narrareach URLs, adjustedPlatforms for any destination that posts other text than the note as written, and destination-specific advisories. ### `list_linkedin_destinations` Refresh and list connected LinkedIn profiles and Company Pages for short-form posts. Does not publish content. - **Use it when:** Call before scheduling a LinkedIn post when the destination is ambiguous. - **Access:** Connected LinkedIn account with post access in the selected account. - **Account selection:** Personal account by default; pass workspace for an authorized team workspace. Pass writer with workspace to select a team writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** None - **Accepted fields:** `workspace`, `writer` - **Conditional fields:** None - **Returns:** Available personal and organization destinations. ### `amend_scheduled_note_content` Preview and edit the text of a queued, text-only LinkedIn post. - **Use it when:** Read readiness and queued text, preview the full replacement, and apply only after user confirmation. - **Access:** Authenticated personal account; the post must belong to you and publishing must not have started. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `id`, `expectedRevision`, `content` - **Accepted fields:** `id`, `expectedRevision`, `content`, `apply` - **Conditional fields:** None - **Returns:** A preview when apply is omitted or false; the updated queued text when apply is true. Media posts, published posts, and scheduled articles are not supported. Read readiness again if the item has changed. ## Articles ### `list_scheduled_posts` List article schedules in your personal account. - **Use it when:** Check an article schedule before retrying, moving, or cancelling it. For Notes and social posts, use list_notes. - **Access:** Authenticated personal account. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** `limit`, `status`, `from`, `to` - **Conditional fields:** None - **Returns:** Article schedule ids, draft summaries, times, destinations, and status. ### `cancel_scheduled_post` Cancel an article schedule from list_scheduled_posts. - **Use it when:** Use with an article schedule id after the user approves cancellation. Prefer cancel_scheduled_item for workflows that handle both articles and Notes. - **Access:** Authenticated personal account; the schedule must belong to you. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `id` - **Accepted fields:** `id` - **Conditional fields:** None - **Returns:** The schedule id and cancellation status. ### `schedule_article` Schedule a full article to supported connected long-form destinations. - **Use it when:** Use after title, article body, audience settings, destinations, and time are approved. - **Access:** Eligible plan plus article write access to every selected destination. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `platforms` - **Accepted fields:** `draftId`, `title`, `contentHtml`, `subtitle`, `coverImage`, `media`, `tags`, `sendToNewsletter`, `isPaidContent`, `paywallMarker`, `addSearchMetadata`, `linkedinShareCommentary`, `linkedinPublicationType`, `linkedinAuthorUrn`, `linkedinNewsletterUrn`, `scheduledFor`, `platformSchedules`, `timezone`, `platforms`, `publication`, `substackConnectionId`, `mediumPublicationId`, `mediumNotifyFollowers` - **Conditional fields:** `mediumPublicationId`: Only valid when platforms includes MEDIUM. Call list_medium_publications and pass its returned id; never guess one. When canPublish is false the story is submitted for editorial review and left unscheduled until an editor accepts it. A rejection by the publication is best-effort — the story still goes to the personal profile and the rejection is returned as a warning. `mediumNotifyFollowers`: Only valid when platforms includes MEDIUM. Defaults to false (no subscriber email). - **Returns:** Accepted article schedules, Narrareach URLs, and non-blocking advisories. ### `list_linkedin_article_destinations` Refresh and list LinkedIn article profiles, Company Pages, and newsletters. Does not publish content. - **Use it when:** Call before scheduling a LinkedIn article when the author or newsletter is not explicit. - **Access:** Connected personal-account LinkedIn integration with article publishing access. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** None - **Accepted fields:** `authorUrn`, `refresh` - **Conditional fields:** None - **Returns:** Available authors, organizations, and newsletters. ### `list_medium_publications` List the Medium publications the connected account can submit stories to. Does not publish content. - **Use it when:** Call before scheduling a Medium article to a publication rather than the personal profile, so the user can confirm the destination and whether it publishes directly or goes to editorial review. - **Access:** Connected personal-account Medium integration. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** `refresh` - **Conditional fields:** None - **Returns:** Connection status and each publication's id, name, and whether the account can publish directly (canPublish) or would submit for editorial review. ### `list_scheduled_items` Review Notes and articles together with their destinations, times, and readiness checks. - **Use it when:** Use to audit upcoming publishing before changing or resubmitting an item. - **Access:** Personal account, or authorized team Notes; team articles are not included. - **Account selection:** Personal account by default; pass workspace for an authorized team workspace. Pass writer with workspace to select a team writer. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** `kind`, `status`, `from`, `to`, `limit`, `workspace`, `writer` - **Conditional fields:** None - **Returns:** Schedule ids, revisions, readiness checks, issues, and suggested next actions based on stored status, not a fresh check of the publishing platform. ### `get_scheduled_item_readiness` Inspect one scheduled Note or article before making changes. - **Use it when:** Use the schedule id to check the current revision and any missing publishing elements. - **Access:** Authenticated personal account; the schedule must belong to you. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** No. - **Required fields:** `id` - **Accepted fields:** `id`, `kind` - **Conditional fields:** None - **Returns:** The revision, linked draftId, destination, readiness checks, and next action. Read article content with get_draft using draftId, or queued Note text with get_note using the schedule id. Article content is the local draft, not a verified copy of the platform schedule. ### `amend_scheduled_item` Preview and confirm a time change for a scheduled Note or article. - **Use it when:** Read readiness first, preview the new time, and apply only after user confirmation. - **Access:** Authenticated personal account; the schedule must belong to you. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `id`, `expectedRevision`, `scheduledFor` - **Accepted fields:** `id`, `kind`, `expectedRevision`, `scheduledFor`, `timezone`, `apply` - **Conditional fields:** None - **Returns:** A preview when apply is omitted or false; the updated schedule when apply is true. This changes timing, not content, media, audience, or destination. ### `reschedule_scheduled_item` Move an authorized queued Note or article to a new time. - **Use it when:** Use after confirming the existing item and replacement time with the user. - **Access:** Authenticated personal account; the schedule must belong to you. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `id`, `scheduledFor` - **Accepted fields:** `id`, `kind`, `scheduledFor`, `timezone` - **Conditional fields:** None - **Returns:** The revised schedule and current destination state. ### `cancel_scheduled_item` Cancel an authorized queued Note or article without deleting its source draft. - **Use it when:** Use only after the user clearly identifies the scheduled item to cancel. - **Access:** Authenticated personal account; the schedule must belong to you. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `id` - **Accepted fields:** `id`, `kind` - **Conditional fields:** None - **Returns:** The item kind, id, and cancellation status. Cancellation does not retract published content. ## Media ### `upload_media` Upload supported image or video bytes for later use in an authorized publishing workflow. - **Use it when:** Use when an agent has media bytes or a data URI that a publishing tool cannot fetch directly. - **Access:** Eligible plan and authenticated upload access. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `kind` - **Accepted fields:** `kind`, `sourceType`, `url`, `data`, `mimeType`, `fileName` - **Conditional fields:** None - **Returns:** A public media URL and reusable media metadata. ## Inspiration ### `list_inspiration_posts` Browse inspiration posts saved by the authenticated user. - **Use it when:** Use when the user asks to draw from their saved inspiration library. - **Access:** Authenticated inspiration read access. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** `limit`, `platform`, `tag` - **Conditional fields:** None - **Returns:** Saved inspiration summaries and source context. ### `get_benchmark_inspiration` Read saved writing experiments and optional inspiration for eligible pilot accounts. - **Use it when:** Use only when the tool is visible and the user asks for eligible benchmark inspiration. - **Access:** Conditional pilot access. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** None - **Conditional fields:** None - **Returns:** Eligible experiment summaries and supporting inspiration. ### `prepare_benchmark_inspiration` Prepare low-confidence draft comparisons from saved examples for eligible pilot accounts. - **Use it when:** Use only when visible, with the user expecting review rather than automatic publication. - **Access:** Conditional pilot access. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `recordId`, `niche` - **Accepted fields:** `recordId`, `niche` - **Conditional fields:** None - **Returns:** Reviewable comparison material; it does not publish content. ## Audience ### `list_reader_activities` List owned Substack likes, comments, and restacks. - **Use it when:** Use to review the audience inbox or locate a comment before replying. - **Access:** Reader activity read access for the selected publication. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** `state`, `type`, `sort`, `cursor`, `limit`, `substackConnectionId` - **Conditional fields:** None - **Returns:** Owned reader activity with pagination information. ### `reply_to_reader_activity` Publish a reply to an owned, replyable Substack comment. - **Use it when:** Use only after the user approves the reply and target comment. - **Access:** Reader activity write access for the selected publication. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `activityId`, `text` - **Accepted fields:** `activityId`, `text`, `idempotencyKey`, `substackConnectionId` - **Conditional fields:** None - **Returns:** Reply confirmation and updated inbox state. ### `update_reader_activity` Move an owned reader activity item between Inbox and History. - **Use it when:** Use when the user asks to triage a specific activity item. - **Access:** Reader activity write access for the selected publication. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `activityId`, `triageState` - **Accepted fields:** `activityId`, `triageState`, `substackConnectionId` - **Conditional fields:** None - **Returns:** The updated activity state. ## Analytics ### `get_platform_analytics` Fetch supported account and post analytics, or return stored metrics. May refresh connection and analytics data; does not publish content. - **Use it when:** Use for platform-specific performance questions, including connected LinkedIn posts. - **Access:** Eligible plan and a connected platform in your personal account. - **Account selection:** Personal account only; do not send workspace or writer. - **Changes data:** Yes. Confirm the intended target and outcome before calling. - **Required fields:** `platform` - **Accepted fields:** `platform`, `recentLimit` - **Conditional fields:** None - **Returns:** Available platform metrics with source and time-window context. ### `get_stats_insights` Read stored Narrareach Stats insights for a selected period. - **Use it when:** Use for reach, engagement, conversion, publishing rhythm, timing, and audience-snapshot questions. - **Access:** Eligible plan and Stats read access. - **Account selection:** Personal account by default; pass workspace for an authorized team workspace. This tool does not accept writer. - **Changes data:** No. - **Required fields:** None - **Accepted fields:** `period`, `from`, `to`, `platforms`, `contentTypes`, `publicationId`, `workspace` - **Conditional fields:** None - **Returns:** Stored Stats outcomes with the selected period and evidence context.