This server enables AI assistants to read Substack publication data and manage drafts, while intentionally preventing publishing or deletion of long-form content.
Read capabilities:
Get current subscriber count
List published or draft posts with pagination (title, date, slug, URL, audience)
Get full content of a specific published post or draft by ID
Get comments on a published post (commenter, body, date, reaction counts)
Write capabilities:
Create new draft posts from markdown (title, subtitle, body, audience: everyone, paid, founding, or free subscribers)
Update existing unpublished drafts (title, subtitle, body, audience)
Upload base64-encoded images to Substack's CDN, returning a hosted URL
Immediately publish short-form Substack Notes (with optional link card attachment)
Intentional limitations (safety by design):
Cannot publish or delete long-form posts — those actions require manual review in Substack's editor
Cannot schedule posts
Allows AI assistants to interact with Substack publications to retrieve subscriber counts, list and read published posts or drafts, and manage draft content by creating or updating posts from Markdown, including support for image uploads.
An MCP server for Substack. Read your publication data and manage drafts from your AI agent. Long-form posts are draft-only by design — no publish, no delete. Short-form Notes publish immediately.
An MCP server for Substack that lets AI assistants read your publication data and manage drafts. The draft list shown in the demo above is sample data, not real account values.
Safe by design — with one loud exception: This server cannot publish or delete long-form posts. Post tools create and edit drafts only; you review and publish manually through Substack's editor. The exception is Substack Notes: create_note and create_note_with_link publish short-form Notes immediately, because Notes have no draft state on Substack. Treat the Note tools as public-publish actions — there is no preview step and no undo from this server. The split is proportionate review, the piece of trust infrastructure for agents this server cares most about: the high-stakes surface gets a human gate, and the exception is stated loudly.
Every tool declares MCP tool annotations, set explicitly rather than left to MCP's defaults (an omitted destructiveHint or openWorldHint defaults to true). Reads carry readOnlyHint: true. Every write is additive, so all writes carry destructiveHint: false. Draft writes are private (openWorldHint: false); upload_image carries openWorldHint: true because it returns a publicly-fetchable CDN URL; and the Note tools carry openWorldHint: true for immediate public publish. Annotations are untrusted hints, so the authoritative wording lives in each tool's description.
Tool | Description |
| Get your publication's current subscriber count |
| List published posts with pagination |
| List draft posts |
| Get full content of a published post by ID |
| Get full content of a draft by ID |
| Get comments on a published post |
| List your publication's sections (categories) with their IDs |
| Get a published post's stats (views, opens, signups, subscribes, reactions) by ID |
| List posts scheduled for future publication (read-only; scheduling stays in Substack's editor) |
Tool | Description |
| Create a new draft from markdown (private) |
| Update an existing draft (unpublished only; private) |
| Upload an image to Substack's CDN — returns a publicly-fetchable (unlisted) URL |
Tool | Description |
| Publish a Substack Note (short-form, publishes immediately) |
| Publish a Note with a link card attachment (publishes immediately) |
Notes have no draft state on Substack, so there is no draft-first option for these two tools.
Publish posts — Publishing long-form posts should be a deliberate human action (Notes are the documented exception above)
Delete — Too destructive for an AI tool
Schedule — Use Substack's editor for scheduling. (list_scheduled_posts reads what you've queued there, but this server never creates, edits, or cancels a schedule.)
Related MCP server: substack-mcp
You can supply credentials two ways: paste them as env vars (below), or run the optional browser login which captures and stores them for you.
Removes the DevTools cookie hunt and the ~90-day re-copy. Playwright is not bundled (it's large), so install it once, then sign in:
npm i -g playwright && npx playwright install chromium
npx --package @conorbronsdon/substack-mcp substack-mcp-login https://yourblog.substack.comA browser opens; sign in to Substack (CAPTCHA included). The tool captures your
session cookie, auto-resolves your user id, and writes them to
~/.substack-mcp/session.json (override the directory with SUBSTACK_MCP_HOME).
The MCP server reads that file automatically whenever the SUBSTACK_* env vars
are unset — so with browser login you can omit the env block entirely.
Storage & security: the file is written 0600 and encrypted with AES-256-GCM
under a key derived from this OS account + machine (never stored). A copied file
is useless elsewhere and casual disk/backup reads see only ciphertext. This is
machine-binding + obfuscation, not a secret vault — code running as you on
this machine can re-derive the key (the same caveat as the plaintext env-var
path). If you prefer, use Option B and let your MCP client handle the secret.
Open your Substack in a browser, then:
Session token: Navigate to your publication, open DevTools → Application → Cookies → copy the value of connect.sid (URL-encoded string starting with s%3A)
User ID: In DevTools Console, run: fetch('/api/v1/archive?sort=new&limit=1').then(r=>r.json()).then(d=>console.log(d[0]?.publishedBylines?.[0]?.id))
Publication URL: Your Substack URL, including custom domain if you have one (e.g., https://newsletter.yourdomain.com or https://yourblog.substack.com)
Add to your claude_desktop_config.json:
{
"mcpServers": {
"substack": {
"command": "npx",
"args": ["-y", "@conorbronsdon/substack-mcp"],
"env": {
"SUBSTACK_PUBLICATION_URL": "https://yourblog.substack.com",
"SUBSTACK_SESSION_TOKEN": "your-session-token",
"SUBSTACK_USER_ID": "your-user-id"
}
}
}
}Add to your .mcp.json:
{
"mcpServers": {
"substack": {
"command": "npx",
"args": ["-y", "@conorbronsdon/substack-mcp"],
"env": {
"SUBSTACK_PUBLICATION_URL": "https://yourblog.substack.com",
"SUBSTACK_SESSION_TOKEN": "your-session-token",
"SUBSTACK_USER_ID": "your-user-id"
}
}
}
}Ask your AI assistant: "How many Substack subscribers do I have?"
Running more than one publication behind a single server? Set a SUBSTACK_PUB_<KEY>_* triplet per publication instead of the plain SUBSTACK_* vars. <KEY> is any name you choose (letters, digits, underscores) — it becomes the publication's lowercase, hyphenated key, e.g. KEVIN_MULDOON → kevin-muldoon.
"env": {
"SUBSTACK_PUB_KEVIN_MULDOON_PUBLICATION_URL": "https://kevinmuldoon.substack.com",
"SUBSTACK_PUB_KEVIN_MULDOON_SESSION_TOKEN": "token-1",
"SUBSTACK_PUB_KEVIN_MULDOON_USER_ID": "111",
"SUBSTACK_PUB_SAPERE_PUBLICATION_URL": "https://sapere.substack.com",
"SUBSTACK_PUB_SAPERE_SESSION_TOKEN": "token-2",
"SUBSTACK_PUB_SAPERE_USER_ID": "222"
}Each triplet is independent, and setting any SUBSTACK_PUB_<KEY>_* variable declares that publication. An incomplete triplet — a missing variable, an empty value, or a whitespace-only value — fails startup with an error naming the key, rather than silently dropping that publication. That matters because a dropped publication is not "one fewer publication": drop the only one and the server falls back to your stored browser-login session; drop one of two and every tool loses its publication parameter, so a call meant for the dropped publication routes silently to the surviving one.
Keys are compared case-insensitively, with _ folded to -. Two names that resolve to the same key (SUBSTACK_PUB_ALPHA_* and SUBSTACK_PUB_Alpha_*) are a startup error too — merging them silently would let one publication's URL pair with another's session token.
<KEY> accepts ASCII letters, digits, and underscores; the three suffixes must be uppercase and the whole name must have no stray whitespace. Anything that begins with SUBSTACK_PUB_ but does not fit that shape — a hyphen in the key, a lowercase suffix, an accented character, a trailing space — is a startup error naming the variable, not a variable that gets quietly ignored. For the same reason as above: an ignored publication is not one fewer publication, it is a silent reroute to a different one.
With two or more publications configured, every tool gains a required publication parameter — one of your configured keys (e.g. kevin-muldoon, sapere above). The calling model must specify one on every call; an unrecognized value is rejected before any Substack API call is made, so a stray write can't land on the wrong publication. With exactly one publication configured — the common case, whether via plain SUBSTACK_* vars or a single SUBSTACK_PUB_<KEY>_* triplet — no publication parameter is added at all; every tool's schema is unchanged from single-publication mode.
Don't mix the two styles: if any SUBSTACK_PUB_<KEY>_* var is set, the plain SUBSTACK_* vars are ignored (with a startup warning) rather than treated as an unnamed extra publication.
SUBSTACK_USER_AGENT and SUBSTACK_REQUEST_TIMEOUT_MS apply to every configured publication — they are not per-publication. The browser-login flow (substack-mcp-login) is single-publication only; multiple publications require the env-var scheme above.
Substack session tokens expire periodically (typically ~90 days). If you get authentication errors, grab a fresh connect.sid cookie from your browser and update the env var (make sure ad blockers are disabled when copying the cookie) — or, if you used the browser login, just re-run substack-mcp-login to refresh the stored session.
Substack publications served on a custom domain (e.g. blog.example.com) sit behind Cloudflare, which can reject non-browser requests with 403 error code: 1010. To avoid this, the server sends a browser User-Agent and a Referer by default, and addresses the publication by its canonical *.substack.com host.
Use the canonical host. Set SUBSTACK_PUBLICATION_URL to the publication's *.substack.com address rather than the custom domain. Calls to the canonical host are served directly; custom-domain calls may 301-redirect and then 401.
Override the User-Agent (optional) via SUBSTACK_USER_AGENT if you need a different browser signature:
"env": {
"SUBSTACK_PUBLICATION_URL": "https://yourblog.substack.com",
"SUBSTACK_SESSION_TOKEN": "your-session-token",
"SUBSTACK_USER_ID": "your-user-id",
"SUBSTACK_USER_AGENT": "Mozilla/5.0 ..."
}Every request to Substack is bounded by a 30-second deadline. Node applies no request timeout of its own — only a 10-second connect timeout — so a host that accepts the connection and then goes silent (a proxy that drops packets rather than refusing them) would otherwise hang a tool call indefinitely. A request that hits the deadline fails with a TimeoutError naming the endpoint and the limit.
Raise or lower it with SUBSTACK_REQUEST_TIMEOUT_MS (milliseconds; a non-numeric or non-positive value is ignored with a warning and the default is used):
"env": {
"SUBSTACK_REQUEST_TIMEOUT_MS": "60000"
}By default the server speaks MCP over stdio — the client spawns it as a subprocess per session, which is what the Claude Desktop/Code configs above assume.
For a persistent, network-reachable deployment (e.g. one server shared by multiple machines, connected to via mcp-remote), set MCP_TRANSPORT=http. This starts a stateless Streamable HTTP server instead:
POST /mcp — the MCP endpoint
GET /health — returns {"status":"ok"} for container healthchecks
docker run -d --restart unless-stopped -p 127.0.0.1:8080:8080 \
-e MCP_TRANSPORT=http \
-e MCP_HTTP_ALLOWED_HOSTS=localhost:8080,127.0.0.1:8080 \
-e MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
-e SUBSTACK_PUBLICATION_URL=https://yourblog.substack.com \
-e SUBSTACK_SESSION_TOKEN=your-session-token \
-e SUBSTACK_USER_ID=your-user-id \
substack-mcpMCP_HTTP_PORT (default 8080) and MCP_HTTP_HOST (default 0.0.0.0, which is what makes a container reachable through -p) configure the listener. Each request gets its own server instance — there's no session state kept between requests, so nothing to lose if the container restarts.
Over stdio the trust boundary is your user account. Over HTTP it is whatever can open a socket to the port — and every request that gets through carries your Substack session cookie, including create_note, which publishes immediately with no undo. The listener therefore starts closed and is opened deliberately:
Variable | Default | Effect |
| loopback names for the bound port | Comma-separated |
| loopback origins for the bound port | Comma-separated |
| unset | When set, requires |
|
| Hard cap enforced while the body streams. Over-limit requests get |
Every one of these is checked before the request is handed to an MCP server, so a rejected request never reaches the Substack API.
Only origin-form request targets are served (POST /mcp, GET /health). An absolute-form target (POST http://elsewhere/mcp), a scheme-relative one (POST //elsewhere/mcp), or a malformed one all get 400 — none of them are routed, and none can take the process down.
Reaching the server under any name other than loopback requires setting MCP_HTTP_ALLOWED_HOSTS yourself. That is the DNS-rebinding defence: without it a page in your browser can resolve an attacker-controlled name to 127.0.0.1 and drive this server as you.
Host and Origin checks are not authentication. They stop a browser being used as a confused deputy; they do nothing about a process running on the same host, which can set any Host it likes and send no Origin at all. On a machine where anything else runs — another MCP server, a dev container, a shared box — set MCP_HTTP_TOKEN. Publish the port to 127.0.0.1 rather than every interface (-p 127.0.0.1:8080:8080), and put the service behind a VPN or private network as you would any other credentialed internal service.
API failures are mapped to a typed error hierarchy (SubstackAPIError base, with AuthenticationError, RateLimitError, ValidationError, NotFoundError, and ServerError subclasses keyed off HTTP status) in src/utils/errors.ts. Every tool call still surfaces the same error response shape on failure — the typed hierarchy just makes the message specific to what went wrong instead of a single generic "Substack API error" string.
Class | Status | Triggered by |
| 401/403 | Expired/invalid session token, or a Cloudflare |
| 429 | Too many requests against the Substack API in a short window |
| 400 | Malformed or invalid arguments passed to a tool (e.g. a missing required field) |
| 404 | The referenced draft, post, or note doesn't exist |
| 5xx | Failure on Substack's side |
| 408 (synthetic) | The request hit the client's own deadline — no response arrived, so there is no real status to report (see Request timeout) |
| any other status | Fallback for unmapped status codes |
Substack error response bodies are inconsistent — sometimes JSON ({"error": "..."} or {"errors": [...]}), sometimes plain text, and sometimes a large Cloudflare HTML block page. extractErrorDetail handles all three: it tries JSON.parse first, falls back to the raw text (trimmed and capped at ~500 characters so a multi-KB HTML page doesn't become the whole error message), and only uses a generic fallback string if the body is empty.
The create_draft and update_draft tools accept markdown and convert it to Substack's native format. Supported:
Paragraphs, headings (h1–h6)
Bold, italic, inline code
Images
Bullet and numbered lists, including nested lists (arbitrary depth, mixed ordered/unordered)
Code blocks (with language)
Blockquotes
Horizontal rules
Tables: Substack's post editor has no table node, so a markdown table cannot be rendered natively. Rather than mangle the pipes into a paragraph, a detected GFM table is preserved verbatim inside a code block — the content survives so you can reformat it (as an image or embed) in Substack's editor.
This server uses Substack's unofficial API. It may break if Substack changes their endpoints.
Session tokens are sent as cookies. Keep your SUBSTACK_SESSION_TOKEN secure.
The server checks your credentials on startup, after the MCP handshake completes, and only warns — it never blocks startup on a network call. Tools still error individually if the token is expired, which is where the failure is actionable.
SIGTERM and SIGINT are handled: the server closes its transport and exits 0, so docker stop returns promptly instead of waiting out the grace period.
git clone https://github.com/conorbronsdon/substack-mcp.git
cd substack-mcp
npm install
npm run buildRun locally:
SUBSTACK_PUBLICATION_URL=https://yourblog.substack.com \
SUBSTACK_SESSION_TOKEN=your-token \
SUBSTACK_USER_ID=your-id \
npm startIssues and pull requests are welcome. Because this server uses Substack's unofficial API, the most useful contributions are fixes when an endpoint changes. If a tool stops working, open an issue with the tool name and the error. The safe-by-design boundary stays: no publish, no delete, no schedule for long-form posts. Notes publish immediately by design and must keep saying so loudly in their descriptions.
Built and maintained by Conor Bronsdon for the Chain of Thought podcast production workflow, where it drafts and reviews newsletter posts before a human hits publish. Conor hosts Chain of Thought, a show about AI infrastructure and how practitioners actually build with it. More tools for creators live in ai-tools-for-creators. Find Conor on X at @ConorBronsdon.
Companion tools:
Transistor-MCP: manage podcast episodes, analytics, and transcripts on Transistor.fm
podcastindex-mcp: search the Podcast Index and track guest appearances
op3-mcp: report downloads, listener geography, and apps from OP3
apple-podcasts-mcp: pull plays, followers, and per-episode listening from Apple Podcasts Connect
gsc-mcp: query search performance, keywords, and sitemaps in Google Search Console
podcast-benchmark: benchmark a show against its peers using only public data
This is an independent personal project, not affiliated with, sponsored by, or endorsed by any company. All views expressed are my own.
MIT
Create a new draft post. Accepts markdown body which is converted to Substack's format. Does NOT publish — creates a draft only.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Post body in markdown format | |
| title | Yes | Post title | |
| audience | No | Who can see this post | everyone |
| subtitle | No | Post subtitle |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, meaning the tool is a write operation. The description adds behavioral context: it accepts markdown and converts it, and it does not publish. This goes beyond the annotations, providing useful details about the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and includes both the core function and a key constraint. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and no output schema. The description covers the main behavior (creating a draft with markdown conversion) and the non-publishing aspect. It does not detail return values or prerequisites, but for a straightforward creation tool, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context for the 'body' parameter by stating 'Accepts markdown body which is converted to Substack's format', which clarifies the expected input format beyond the schema's description. This extra information warrants a score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new draft post'), the resource ('draft post'), and distinguishes from publishing ('Does NOT publish'). The verb 'create' and resource 'draft post' are specific, and the description differentiates from siblings like 'update_draft' or 'get_draft'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Does NOT publish — creates a draft only', which helps the agent understand when to use this tool versus a publishing tool. It provides clear context but does not explicitly mention when not to use it or name specific alternatives beyond the implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Substack Note (short-form content). Accepts markdown text. PUBLISHES IMMEDIATELY to your public Notes feed — Notes have no draft state on Substack, and this server has no delete tools, so there is no undo from here.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Note content in markdown format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds critical behavioral details: immediate publication, no draft state, irreversible action due to lack of delete tools. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no waste: purpose, input format, and critical caveat. Information is front-loaded and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers purpose, input, and behavioral traits. Could mention return value (e.g., created note object), but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description only restates 'markdown text' already present in the schema. No additional semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a Substack Note (short-form content) and accepts markdown text, distinguishing it from sibling tools like create_draft (long-form) and create_note_with_link (note with a link).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly warns that notes publish immediately with no draft state and no undo, implying when to use (for instant public notes) and when not (if drafts or reversibility are needed). Could be more explicit about alternatives, but the context with siblings helps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Substack Note with a link attachment, displayed as a rich card below the note text. PUBLISHES IMMEDIATELY to your public Notes feed — same caveats as create_note: no draft state, no undo from this server.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to attach as a link card | |
| body | Yes | Note content in markdown format |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds critical behavior not in annotations: immediate publication, no draft state, no undo. This matches the annotations (readOnlyHint=false, destructiveHint=false) and provides full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, then caveats. No wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description covers purpose, behavior, and caveats. It references create_note for additional context. Could mention error handling or response format, but not essential for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions. The tool description adds the detail that the URL is displayed as a rich card, but this is already in the schema. No substantial additional meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a Substack Note with a link attachment displayed as a rich card. It distinguishes from sibling tools by explicitly mentioning the link card and referencing 'create_note' for plain notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'same caveats as create_note: no draft state, no undo', which guides when to use it versus creating drafts. However, it does not explicitly mention that for plain notes one should use 'create_note', though this is implied by the context of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full content of a draft post by ID. Returns title, body, metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| draft_id | Yes | The draft ID to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description does not need to restate that. It adds value by specifying return content (title, body, metadata), but no other behavioral details like permissions or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action and return values. No wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description covers the essential purpose and return structure. Minor gaps include lack of error handling or metadata format, but overall adequate given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (draft_id described as 'The draft ID to retrieve'). The description adds no additional meaning to the parameter beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Get the full content of a draft post by ID') and the return values ('title, body, metadata'). This clearly distinguishes it from siblings like get_post or list_drafts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies you need a draft ID, but does not differentiate from get_post or list_drafts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full content of a published post by ID. Returns title, body HTML, metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | The post ID to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds that it returns 'title, body HTML, metadata', but no additional behavioral traits. No contradiction, but adds minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, directly states purpose and output. No wasted words. Front-loaded with action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and known annotation (readOnlyHint), the description fully explains what is returned, making it complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes post_id as 'The post ID to retrieve'. The description only repeats 'by ID', adding no new meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'a published post by ID', and the return value 'title, body HTML, metadata'. It distinguishes from sibling tools like 'get_draft' (draft vs published) and 'list_published_posts' (list vs single).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a published post's full content, but does not explicitly state when to use this over alternatives like 'get_draft' or 'list_published_posts'. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get performance stats (views, emails sent/delivered/opened, signups, subscribes, estimated value, comments, reactions) for a published post by ID. Substack has no per-post stats endpoint, so this searches your 500 most recent published posts for the ID; returns a not-found note if it isn't among them.
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | The published post ID to get stats for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds critical behavioral context beyond the readOnlyHint annotation: the tool searches a limited set of recent posts and returns a not-found note if absent. This fully discloses the workaround behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence lists all returned stats, the second explains the internal search limitation. Every word is useful and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description fully covers what to expect (list of stats fields), the search limitation, and the not-found behavior. It is sufficient for an agent to decide when to call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the one parameter (post_id) with a basic description. The tool description adds context that the post must be published and that the search is limited to the 500 most recent posts, which aids correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'performance stats for a published post by ID'. It lists specific metrics (views, emails, etc.) and distinguishes from siblings like get_post (retrieves post content) and get_post_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes the limitation that Substack has no per-post endpoint and that it searches the 500 most recent published posts. This guides when to use (only for recent posts) and when not (if post not among recent 500). However, it does not name alternative tools for stats beyond that scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comments on a published post. Returns commenter name, comment body, date, and reaction counts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max comments to return (default 20) | |
| post_id | Yes | The post ID to get comments for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, which aligns with 'Get comments'. Description adds value by specifying exact return fields, going beyond annotations. No contradictory or missing behavioral info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource. No unnecessary words, concise and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple read-only tool. Specifies return fields and limit behavior. Could mention pagination or sorting, but not essential given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description doesn't add input parameter details but compensates by explaining output semantics (returned fields) since output schema is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get comments on a published post' with specific return fields (commenter name, comment body, date, reaction counts). Distinguishes from sibling tools like get_post and create_draft by focusing on comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for use (published post) but lacks explicit guidance on when to use vs. alternatives. No exclusion criteria or sibling comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your publication's sections (categories). Returns each section's id and name. Use a section id as section_id when creating or updating a draft to file it under that section.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, and the description adds that it returns id and name, which is consistent and sufficient. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose and output, second gives usage guidance. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description fully covers what the tool does, returns, and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description does not need to add parameter explanations, meeting the baseline for 0 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'sections', and it distinguishes itself from sibling tools by focusing on listing categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on using the section ID for drafts, which is the primary use case. However, it does not mention when not to use it, but that is acceptable for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current subscriber count for your Substack publication. Returns precision: 'exact' when the API reports a true count, 'approximate' when only Substack's rounded value is available (the real number is that or higher — render it hedged, e.g. '1,000+'), or 'unavailable' with count -1. Never treat an approximate value as exact.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, but the description goes beyond it by explaining the three precision modes ('exact', 'approximate' with the hedged rendering guidance, and 'unavailable' with count -1). This is genuinely useful behavioral context about return value semantics, not just repetition of the annotation. It could add what errors occur or rate limits, but for a read tool this is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero waste. Every sentence adds value: purpose and precision-mode semantics, and the critical warning not to treat approximate as exact. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 0-parameter read tool with no output schema, the description explains the return shape (precision modes and count values) thoroughly. It covers the edge case of 'unavailable' and the rendering guidance. Complete enough for an agent to invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters, there's nothing for the description to clarify. The baseline of 4 applies for zero-parameter tools; the description appropriately focuses on return-value semantics instead, which is the semantically meaningful content here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the current subscriber count for a Substack publication. The verb+resource (get subscriber count) is specific and distinguishes it from siblings, which all deal with posts, drafts, sections, and analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives, but for a 0-parameter retrieval tool the usage context is largely self-evident. It doesn't provide when-not-to-use guidance or alternatives, but given there's no close sibling (no other subscriber-related tool), the lack of exclusions is acceptable. The precision-mode guidance is user-facing behavior rather than tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List draft posts. Returns title, creation date, and audience for each draft.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max drafts to return (1-50; Substack rejects anything higher, so larger values are clamped) | |
| offset | No | Number of drafts to skip |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description aligns (a listing operation is read-only). The description adds value by noting the returned fields, which supplements what annotations provide. There is no contradiction, and it adds contextual detail about the output shape beyond the annotation's safety declaration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that states purpose and output fields with zero waste. Could arguably add sibling-differentiation guidance, but as written it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description's statement of returned fields (title, creation date, audience) is the only return-shape documentation—it's helpful but minimal. For a simple listing tool with readOnly annotation and two well-documented params, this is adequate but not rich; pagination behavior or sorting could be noted to improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents both params (limit, offset). However, the description adds no param-related meaning beyond the schema—it doesn't mention pagination, defaults, or how limit/offset interact. Since schema coverage is high, baseline is 3, but the description contributes zero additional parameter semantics beyond what's structured, so a slight deduction is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource ('List draft posts') and states the returned fields (title, creation date, audience). It doesn't explicitly distinguish from siblings like list_published_posts or list_scheduled_posts, but the resource name (drafts) along with the returned fields is reasonably clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance. However, the sibling set includes list_published_posts and list_scheduled_posts, and 'draft' in the name plus 'audience' field implies it's for unpublished drafts. Context is implied but not stated; no exclusions or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List published posts with pagination. Returns title, date, slug, and URL for each post.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max posts to return (1-50; Substack rejects anything higher, so larger values are clamped) | |
| offset | No | Number of posts to skip |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description consistently aligns by listing published posts (a read operation). The description's main added value is the return field disclosure. It doesn't contradict annotations. Some behavioral detail (pagination clamping, rate limits) is in the schema rather than description, which is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action, zero filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool with readOnlyHint annotation, 100% schema coverage on both params, and no output schema, the description is adequate. It declares the return fields which compensates for the missing output schema. Could mention pagination behavior or total counts, but not critical for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both limit and offset documented including the Substack clamping behavior. The description itself adds minimal parameter meaning, but the schema does the heavy lifting, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb+resource ('List published posts') and specifies the return payload shape (title, date, slug, URL). It clearly distinguishes from siblings like list_drafts and list_scheduled_posts by scoping to published posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for browsing published posts, and the sibling list distinguishes it from drafts/scheduled posts. However, there is no explicit when-to-use guidance or alternative naming, though the tool name itself is reasonably unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List posts scheduled for future publication, soonest first. Read-only visibility into what's queued — scheduling itself is done in Substack's editor (this server does not schedule, publish, or delete long-form posts). Returns id, title, audience, and scheduled time (trigger_at).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max posts to return (1-50; Substack rejects anything higher, so larger values are clamped) | |
| offset | No | Number of posts to skip |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable context beyond the readOnlyHint annotation: it explicitly discloses that scheduling/publishing/deleting is NOT performed by this server, preventing the agent from assuming this tool can schedule posts. It also clarifies the read-only nature with 'Read-only visibility into what's queued.' The readOnlyHint already covers the safety profile, and the description reinforces it with concrete scoping.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero waste. Front-loaded with the primary purpose, immediately clarifies scope boundaries (what it doesn't do), and lists the return fields. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with 100% schema coverage, full param documentation, a strong readOnlyHint annotation, and clear scope disambiguation from siblings, the description is complete. It explains what it returns, the ordering, what it does NOT do, and its relationship to the broader system.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (limit, offset) are already fully documented in the schema with their defaults and clamping behavior. The description adds the list ordering ('soonest first') which is useful context, but doesn't add significant param semantics beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: 'List posts scheduled for future publication, soonest first.' Clearly distinguishes from siblings like list_published_posts and list_drafts by focusing on scheduled/future posts. States exactly what is returned (id, title, audience, trigger_at).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes 'scheduling itself is done in Substack's editor' and that 'this server does not schedule, publish, or delete long-form posts,' which disambiguates from create/update tools. It also clarifies this is read-only visibility into the queue. A clear alternative is implicitly established via the sibling list_published_posts, though it doesn't explicitly name the alternative tool for publishing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing draft post. Only works on unpublished drafts. Accepts markdown body.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | New body in markdown format | |
| title | No | New title | |
| audience | No | Who can see this post | |
| draft_id | Yes | The draft ID to update | |
| subtitle | No | New subtitle |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-destructive modification (destructiveHint=false, readOnlyHint=false). The description adds that it accepts markdown body and only applies to unpublished drafts, which provides some behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with only two sentences and no fluff. Every word serves a purpose, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the purpose and constraint are clear, the description does not clarify whether updates are partial or full, nor does it mention return values or error scenarios. Given the lack of an output schema, some additional context would be helpful for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters and their purposes. The description mentions 'accepts markdown body', but this is also covered by the body parameter's description in the schema. No additional semantic value is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing draft post' which accurately conveys the action and resource. The additional constraint 'Only works on unpublished drafts' further distinguishes it from siblings like get_draft or list_drafts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides usage by specifying that it only works on unpublished drafts, but it does not explicitly state when to use this tool over alternatives like create_draft or get_draft. Still, the constraint provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload an image to Substack's CDN. Provide exactly one of image_base64 (a base64 data URI) or image_path (a local file path). Returns a hosted image URL that is publicly fetchable by anyone with the link (an unlisted asset — not attributed to you or added to your feed).
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | No | Absolute path to a local image file (e.g., "/Users/me/pic.png"). Read and encoded automatically; MIME type inferred from the extension. Mutually exclusive with image_base64. | |
| image_base64 | No | Base64-encoded image with data URI prefix (e.g., "data:image/png;base64,..."). Mutually exclusive with image_path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description explains beyond annotations: notes that the returned URL is publicly fetchable, unlisted, not attributed to user. Annotations indicate readOnlyHint=false (write) and openWorldHint=true, which description complements well, no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, every sentence adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, description fully explains return value (hosted URL) and behavioral traits. For a two-parameter upload tool, it is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds clarity on mutual exclusivity and gives examples of data URI prefix and file path format, which goes beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Upload an image to Substack's CDN' with specific verb and resource. Distinguishes from sibling tools, none of which involve image uploads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to provide exactly one of two mutually exclusive parameters. While it doesn't explicitly state when not to use it, the context of siblings makes it clear this is the only upload tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.6.2list_drafts1 field changedInput schema / properties / limit / descriptionPrevious value: -"Max drafts to return (1-100)"New value: +"Max drafts to return (1-50; Substack rejects anything higher, so larger values are clamped)"list_published_posts1 field changedInput schema / properties / limit / descriptionPrevious value: -"Max posts to return (1-100)"New value: +"Max posts to return (1-50; Substack rejects anything higher, so larger values are clamped)"list_scheduled_posts1 field changedInput schema / properties / limit / descriptionPrevious value: -"Max posts to return (1-100)"New value: +"Max posts to return (1-50; Substack rejects anything higher, so larger values are clamped)"v0.6.0upload_image3 fields changedInput schema / properties / image_base64 / descriptionPrevious value: -"Base64-encoded image with data URI prefix (e.g., \"data:image/png;base64,...\")"New value: +"Base64-encoded image with data URI prefix (e.g., \"data:image/png;base64,...\"). Mutually exclusive with image_path."Input schema / properties / image_pathAdded value: +{
+ "description": "Absolute path to a local image file (e.g., \"/Users/me/pic.png\"). Read and encoded automatically; MIME type inferred from the extension. Mutually exclusive with image_base64.",
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "image_base64"
-]v0.5.0get_post_analyticsget_sectionslist_scheduled_postsv1.0.0create_draftcreate_notecreate_note_with_linkget_draftget_postget_post_commentsget_subscriber_countlist_draftslist_published_postsupdate_draftupload_imageEach tool targets a distinct action or resource: drafts, notes, published posts, sections, subscribers, scheduled posts, and image upload. There is no overlap or ambiguity between the tool purposes.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., create_draft, get_post_analytics, list_drafts). The naming convention is uniform and predictable.
14 tools is well-scoped for a Substack publishing server. It covers drafting, notes, posts, analytics, comments, sections, subscribers, scheduling, and image upload—each tool earns its place without redundancy.
Critical lifecycle operations are missing: no way to publish drafts, delete content (posts, notes, drafts), or schedule long-form posts. The server creates drafts and notes but leaves users unable to complete the publishing workflow within the toolset.
WordPress MCP server: publish posts, AI images, SEO and full site management, self-hosted
MCP server for QPost — lets AI agents publish video and image posts to YouTube, TikTok, Instagram.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/conorbronsdon/substack-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
