Substack MCP Server

create_note_with_link

Publish a Substack Note with a link attachment shown as a rich card below the text. The note goes live to your public feed immediately; no draft state or undo is available.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`url`	Yes	URL to attach as a link card
`body`	Yes	Note content in markdown format

Output Schema

TableJSON Schema

Name	Required	Description	Default
`id`	Yes
`body`	No
`date`	No
`message`	Yes
`attachment_id`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "attachment_id": {
+      "$ref": "#/properties/message"
+    },
+    "body": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "date": {
+      "$ref": "#/properties/body"
+    },
+    "id": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "message": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "message",
+    "attachment_id"
+  ],
+  "type": "object"
+}

First observedv1.0.0Mar 13, 2026

TDQS

A4.5/5.0

Behavior5/5

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

The description explicitly discloses important behavior beyond the annotations: PUBLISHES IMMEDIATELY to a public feed, no draft state, and no undo from the server. This is valuable because annotations only say the tool is not read-only and not destructive; they do not convey irreversibility or public visibility.

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?

Two tight sentences with no wasted words. The main purpose is front-loaded, followed by the critical publishing warning. The formatting with caps draws attention to the most important behavioral caveat without adding bulk.

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

Completeness5/5

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

For a two-parameter tool with a complete schema and an output schema present, this description provides everything needed to call it correctly: what it does, how it behaves, when it publishes, and the lack of undo. No critical operational gap remains.

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

Parameters4/5

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

The schema already covers both parameters with 100% coverage, so the baseline is 3. The description adds meaning by explaining the presentation relationship: the link is shown as a rich card below the note text, which clarifies how the url and body parameters interact beyond their individual schema descriptions.

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

Purpose5/5

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

The description states a specific verb ('Create'), a specific resource ('Substack Note with a link attachment'), and the key differentiator: the link is displayed as a rich card below the note text. This clearly separates it from the sibling create_note and other note-related tools.

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?

The context is clear enough: use this to publish a note with a link attachment, and it publishes immediately. However, it does not explicitly say when to prefer this over create_note, nor does it state exclusions like 'for plain text-only notes, use create_note instead.' The reference to 'same caveats as create_note' implies the relationship but does not provide explicit routing guidance.

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