Skip to main content
Glama
Sign In
substack-mcp

substack-mcp

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Update a draft

update_draft
Idempotent

Modify fields of an unpublished Substack draft without resending the whole post. Pass only the draft ID and the properties you want to change, such as title or body.

Instructions

Change any part of an existing draft. Only the fields you pass are touched, so you can update just the title without resending the body. Works on unpublished drafts.

Input Schema

NameRequiredDescriptionDefault
idYesDraft id, from create_draft or list_drafts.
bodyNoPost body. Markdown by default. Supported: headings, bold, italic, inline code, strikethrough, links, images, nested lists (any depth, ordered and unordered mixed), fenced code blocks with a language, blockquotes and horizontal rules. Two things worth knowing: - A line containing only a YouTube, X, Spotify or Vimeo URL becomes a real embedded player, not a link. Put the URL inside a sentence if you want a plain link. - Write <paywall> on its own line to mark where the paywall starts. Everything after it is for paying subscribers only. One per post. Markdown tables have no equivalent in Substack's editor, so they are preserved verbatim in a code block rather than being mangled.
typeNoPost type. 'newsletter' is the normal long-form post.
titleNo
audienceNoWho can read it. 'everyone' is public, 'only_free' is any subscriber, 'only_paid' and 'founding' are paying tiers.
subtitleNo
section_idNo
body_formatNoHow to read `body`. 'auto' detects it and is almost always right. Use 'prosemirror' to send a Substack document directly.
cover_imageNo
publicationNoWhich connected publication to act on, matched loosely against its hostname (for example 'example.substack.com' or just 'example'). Defaults to the first connected publication.
social_titleNo
search_engine_titleNo
search_engine_descriptionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv3.0.1
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • removedInput schema / additionalProperties
      Removed value: -false
  2. First observedv2.1.1

TDQS

A3.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes beyond the annotations by disclosing PATCH-style semantics ('Only the fields you pass are touched') and a state restriction to unpublished drafts. This is consistent with idempotentHint=true and non-destructive, and adds genuinely useful call behavior. It does not say whether the updated draft is returned or how a published-draft rejection surfaces.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core action, then the partial-update rule, then the state scope. No filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter mutation with no output schema and low schema coverage, the description covers the key semantic (partial update) and scope (unpublished) but omits return behavior and failure modes. Adequate minimum, not sufficient for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 46%, and several parameters (title, subtitle, section_id, cover_image, social_title, search_engine_title/description) have no schema description at all. The description only illustrates the mechanism using title and body, so it does not compensate for the undocumented half of the 13-parameter surface.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Change any part of an existing draft') and adds a scope constraint ('Works on unpublished drafts'). It distinguishes the operation from create/get/delete, but never differentiates it from the sibling set_draft_body, which also modifies draft body content, leaving a real ambiguity unresolved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Works on unpublished drafts' gives an explicit applicability boundary, and the partial-update note implies the intended use case. However, no alternative is named (set_draft_body, publish_draft, create_draft) and there is no statement of what happens when the draft is already published, so the agent must infer routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools