Substack MCP Server
Server Quality Checklist
Latest release: v1.3.0
- Disambiguation4/5
Most tools have clearly distinct purposes, but a few pairs overlap, such as list_subscribers/export_subscribers and get_publication_stats/get_analytics. However, descriptions clarify these boundaries, making misselection unlikely.
Naming Consistency5/5All tool names follow a consistent verb_noun snake_case pattern (e.g., create_draft_post, list_subscribers, set_post_body). No mixed casing or irregular conventions are present, making the naming highly predictable.
Tool Count2/5With 27 tools, the server exceeds the guideline of 3-15 for a well-scoped set and falls into the 'too many' category. While the domain is broad, several tools could be consolidated, such as the analytics and stats tools.
Completeness2/5The server covers core draft and publishing workflows, but significant gaps exist: no way to edit or delete published posts, no tag removal, no scheduling, and no subscriber management. These omissions create dead ends after publishing.
Average 4.3/5 across 27 of 27 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 41 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only states that it creates a draft post. It does not disclose return values, side effects, permissions, or the relationship to publishing, making it insufficient for transparent behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the action and resource, matching the requirement for efficiency, though it could have been slightly more informative without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too minimal for the tool's context. It lacks alternative guidance, return values, and fails to mention that the tool creates only a draft (not publishing). While the schema compensates for parameters, the overall description is not complete enough for an agent to use the tool correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The tool description adds no parameter information, but the input schema descriptively covers all three parameters, with particularly rich semantics for 'body' regarding Markdown handling and JSON validation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the resource 'draft post' on Substack, making the core purpose unambiguous. However, it does not differentiate from siblings like update_draft or set_post_body, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or that set_post_body is preferred for structured content (which the schema does mention, but the tool description itself lacks this context).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It adds useful context about account scoping and feed selection, but it does not mention pagination, response format, or failure behavior. This is a read operation, so the risk is lower, but the transparency is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loads the core purpose, and every sentence contributes useful information. There is no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool returns and how to select feeds, but without an output schema or annotations, it leaves the response structure and pagination behavior implicit. The schema's cursor parameter hints at `next_cursor`, but the description itself is not fully complete for an agent that needs to understand the full call context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for all four parameters with descriptions. The description adds a small amount of value by explaining how `tab` and `include_tabs` interact, but it does not expand on `limit` or `cursor` beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') with a clear resource ('Substack Notes feed') and scopes it to 'this account,' distinguishing it from sibling tools like get_profile_feed and list_reader_posts. It immediately tells the agent what the tool does and what domain it operates in.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete guidance on how to use the tool ('Pick the feed with `tab`') and how to discover available options ('set include_tabs to discover the ids available'). It does not explicitly mention when to use this tool over alternatives, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it 'reads' a thread, implying a non-mutating operation, and describes what is returned (author, position). No annotations are provided, so the description carries the burden for behavioral disclosure. It doesn't mention permissions, edge cases, or limitations, but the read-only nature is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The first states the action and expected result; the second provides sourcing guidance. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality and return content (author, position). With no output schema, it gives enough context for an agent to understand the tool's purpose. It omits details like pagination or failure modes, but for a simple single-thread read, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameter descriptions are rich: comment_id includes 'from get_reader_feed... Without the c- prefix' and include_replies has a clear default and purpose. The description text itself doesn't add parameter details, but the schema already provides full semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and clearly identifies the resource as 'one Note or comment together with the replies beneath it', explicitly mentioning author and position. It also tells the user where to get the id (get_reader_feed or get_profile_feed), which distinguishes it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Take the id from get_reader_feed or get_profile_feed', providing a clear context for when this tool is used. However, it doesn't explicitly name alternatives or when not to use this tool, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions the default-to-own-account behavior and the type filter, but omits pagination details, authentication requirements, and any safety confirmation beyond the word 'Read'. This leaves some gaps in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose and key behaviors. Every clause adds value: 'Read...', 'Defaults to your own account...', and 'pass user_id for anyone else.' No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, default behavior, and content-type filter, which is solid for a read-only feed tool. While it doesn't outline the response shape or pagination, the schema supplies parameter details, and the description is reasonably complete given its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds conceptual framing for 'notes'/'posts' and clarifies the default user, but does not materially exceed what the schema already provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads one account's published content (Notes, posts, or both), using the specific verb 'Read' and identifying the resource. It also distinguishes from sibling tools by clarifying the profile scope and defaulting to the agent's own account.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context: defaulting to your own account for listing your Notes, and passing a user_id for anyone else. It doesn't explicitly name alternatives, but the guidance is sufficient to decide when to use this tool versus a general feed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It reveals that each post is 'summarised' and includes 'read state and reading progress,' which goes beyond the tool's name. However, it does not disclose pagination behavior, error conditions, or permissions—though it is clearly a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and ends with an actionable pointer to the sibling tool. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description adequately explains what is returned (summaries, read state, progress) and points to the tool for full content. It could mention explicit ordering (e.g., 'newest first'), but 'recent' implies recency, making this largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for both parameters (after and limit) with clear descriptions. The tool description adds no parameter-specific detail beyond what the schema already conveys, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List'), a resource ('posts'), and a scoped context ('publications this account subscribes to — the reader Inbox'). It also distinguishes itself from sibling tools like list_posts and get_reader_feed by referencing the reader Inbox and explicitly naming get_reader_post as the tool for reading a single post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use (reader Inbox) and explicitly mentions an alternative ('use get_reader_post to read one'). It does not explicitly exclude other sibling tools like get_reader_feed, but the reader Inbox framing makes the appropriate usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses that comments withheld by automod are reported separately under automod_hidden_count, and enumerates the per-comment fields (author, text, reaction and reply counts, position). It does not mention sorting or pagination, but the schema covers the limit parameter, and the disclosed details go beyond a generic 'read comments' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the primary purpose, and each sentence adds substantial value: the first defines the action and return contents, the second clarifies a non-obvious behavioral nuance (automod handling). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain what is returned. It does so thoroughly by listing the fields for each comment and the automod_hidden_count. Combined with the schema's parameter documentation, this gives a complete picture for a read-only tool with two parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage: both 'limit' and 'post_id' have clear descriptions with ranges and defaults. The description adds no additional parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('comments on one of your posts'), clearly stating what the tool does. It also distinguishes itself from siblings like get_comment_thread and comment_on_post by focusing on the comments of a specific post, including thread position and automod handling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for one's own posts ('on one of your posts') and notes that automod-hidden comments are counted separately, which is useful context. However, it does not explicitly state when to prefer this over sibling tools like get_comment_thread, nor does it provide exclusion criteria, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behaviors: creating the tag if it doesn't exist, working on drafts and published posts, and returning 'already_tagged' instead of failing. It doesn't mention auth/rate limits or the return payload, but covers the most important behavioral traits for a tag-adding operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding distinct information: the core action, scope (drafts/published), and idempotent behavior. No redundant phrasing, front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and full schema coverage, the description is largely complete. It covers edge cases (already tagged, missing tag creation) and scope. However, with no output schema, it doesn't state the return format, which would be helpful but not critical for this straightforward mutation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-described. The description adds little beyond the schema: it mentions 'by tag name' but the schema already explains tag_name matching and create_if_missing. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Add a tag to a post, by tag name'. It also distinguishes from siblings by noting it works on drafts and published posts and creates the tag if missing, which differentiates it from read-only tools like get_post_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: for adding tags to posts, including drafts. It also specifies behavior for already-tagged posts and tag creation, but doesn't explicitly mention alternatives or when not to use it. However, sibling tools are clearly read-only, so the usage context is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavioral traits. It explicitly says 'Read' and describes the return scope (full body, audience and email settings), clarifying that this is a non-destructive operation. It adds context about the id source, but doesn't discuss error handling or auth, which is acceptable for a straightforward read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first states the core function and scope, the second gives actionable guidance on sourcing the id. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter, no output schema, and no annotations, but the description adequately covers the read operation by explaining what is returned (full content including body and settings) and how to obtain the id. It doesn't cover authentication or error scenarios, but given the simplicity, it's complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter, including its source via list_posts and create_draft_post. The description repeats this guidance in prose, adding no novel semantic value. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: reading one draft post in full, including body and audience/email settings. It distinguishes from sibling tools like list_posts (lists drafts) and update_draft (modifies), making the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs the user to obtain the id from list_posts or create_draft_post, indicating the appropriate workflow. It implies this is for fetching full draft details rather than modifying or deleting, but doesn't explicitly state when not to use it. This is adequate guidance for a simple read tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that each post is returned as a summary and that unpublished posts require get_draft for full content, which is useful behavioral context. It also implies read-only behavior by using 'list' and does not mention side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the main purpose and followed by a useful note about output and an alternative tool. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is straightforward, and the description covers its key features (statuses, search, pagination, sort) and mentions the output format (summary). With no output schema, it gives a useful hint about what is returned. It sufficiently addresses the tool's purpose within the context of the sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all parameters. The description adds some context by summarizing the statuses and mentioning search/pagination/sort, but it doesn't significantly supplement the parameter descriptions beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), the resource (posts of your Substack publication), and the scope (drafts, published, scheduled). It also mentions supporting search, pagination, and sorting, and explicitly distinguishes from get_draft for full content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (listing posts by status) and explicitly points to get_draft for full content of unpublished posts, serving as an alternative. It doesn't explicitly state when not to use it, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the replacing/destructive nature, the result verification behavior ('reports how many nodes of each type were stored'), and a key constraint ('An image must already be hosted by Substack'). It does not mention permissions, rate limits, or what happens to an existing body, but those are not expected in every description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, each carrying distinct value: purpose, uniqueness + content types, prerequisite workflow, result verification, and image constraint. No filler, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a very complex nested ProseMirror schema and no output schema, the description covers the essential selection and invocation context: what it replaces, why it is unique, the prerequisite, the verification result, and a critical input constraint. It omits explicit error/return details, but given the schema's exhaustive structure, this is a strong, complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 the image-hosting constraint and the create_draft_post prerequisite, but these largely echo or lightly augment the schema's own notes (e.g., draft_id 'as returned by list_posts or create_draft_post'). It does not add substantial meaning beyond the highly detailed schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb-resource pair: 'replace the body of a draft with a Substack document.' It explicitly differentiates from siblings by stating it is 'the only way to write structured content' and enumerates the supported node types (headings, lists, links, code blocks, images, buttons, paywall).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit workflow: 'Create the draft first with create_draft_post, then call this with its id.' The phrase 'the only way to write structured content' signals when to prefer it over alternatives like update_draft. However, it does not explicitly name update_draft as the alternative for non-structured edits, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes on the full burden. It discloses key behavioral traits: covers the whole archive, supports paging, and ignores any date filter. It also implies read-only behavior by 'Rank the posts'. It does not mention permissions, rate limits, or the exact response shape, but the core behaviors are well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the verb and resource, then provides concrete usage examples. It is composed of two information-dense sentences that each earn their place. It is slightly long, but not padded, and does not waste words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and a moderately complex behavior (43 metrics, paging, no date filter), the description is quite complete. It explains primary use cases, the no-date-filter limitation, and the paging approach. Minor gaps like draft inclusion or exact return fields are not critical for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantic context, especially for order_by, by giving concrete examples like 'signups' for list growth and 'estimated_value' for worth, which goes beyond the schema's generic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Rank the posts') with a clear object ('of your Substack publication') and a well-defined scope (43 per-post metrics). The focus on per-post metrics distinguishes it from siblings like get_publication_stats and get_analytics, which likely report aggregate stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context for when to use the tool, such as identifying which posts grew the list or cost subscribers, and also gives practical guidance on the absence of a date filter, recommending sorting and paging instead. However, it doesn't explicitly name alternative tools for aggregate stats, so it stops short of a full when-to-use vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return payload (HTML body, author, stats, audience) and warns about the size trade-off with include_body. The verb 'read' implies a safe, non-mutating operation, though it does not explicitly state side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main purpose, and every sentence adds value: scope, return content, and unique usage. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with two parameters and no output schema, the description is complete. It covers what the tool does, when to use it, what it returns, and the trade-offs of the optional parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add new parameter-level details beyond the schema, but it reinforces that the body is HTML and that include_body controls body inclusion, matching the schema's explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Read one post in full, from any publication — not just your own.' It uses a specific verb-resource combination and distinguishes itself from siblings by noting it is 'the only way to read the text of someone else's post.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, emphasizing that it works for any publication and is the only way to view others' content. It does not explicitly name alternatives for reading your own posts, but the unique scope makes usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly states the operation is a read ('Read the account'), lists returned fields, and explains the relationship to SUBSTACK_PUBLICATION_URL. This gives the agent a transparent view of safety and outcome, though it could go further with pagination or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero fluff. The first sentence states purpose and payload, the second gives the distinguishing use case. Perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description covers purpose, return contents, and a specific use case (publication discovery). Nothing critical is missing; it is complete for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of the 'full' parameter. The tool description does not explain the parameter, but the schema does. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds no extra parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Read the account behind the session'. It specifies the exact data returned (id, handle, name, bio, and publications) and distinguishes this tool's purpose from any sibling by noting it reveals all reachable publications, not just the one from SUBSTACK_PUBLICATION_URL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete use case: discover which publications the session can reach beyond the single publication URL. This implies when to use the tool, though it does not explicitly mention alternatives or exclusions. The guidance is sufficient for context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of disclosure. It accurately describes what the tool returns (name, slug, hidden status) and adds valuable context about UUIDs and the lack of need for a tag id in add_tag_to_post. It does not mention pagination or authentication, but for a simple list operation this 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences that front-load the purpose and output, followed by a useful clarification about UUIDs and the related tool. Every word earns its place, and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list operation with one optional parameter and no output schema, the description provides all essential context: the exact output fields, the significance of tag ids, and a pointer to a related tool. It leaves no critical gaps that would prevent an agent from using it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the only parameter, include_hidden, including its default value and rationale. The description adds no additional parameter-level detail, which is appropriate given the schema coverage is 100%. Baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List every tag defined on your Substack publication, with its name, slug and whether it is hidden.' It specifies the resource (publication tags), the verb (list), and the output fields, making it distinct from sibling tools like get_post_tags and add_tag_to_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case: finding a tag id (since ids are UUIDs). It also notes that add_tag_to_post takes a name and does not need the id, offering a clear when-not-to-use scenario. However, it does not explicitly compare against get_post_tags, leaving some ambiguity as to when one would choose this over that similar-sounding tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the refusal behavior for published posts, explains the shared endpoint, and highlights irreversibility for live posts. However, it does not explicitly state whether draft deletion is permanent, though 'delete' implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, action-first, with the caveat clearly stated. Every word earns its place; no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool with no output schema, the description covers purpose, usage boundaries, and a critical behavioral caveat. It omits return values, but that is arguably secondary for a destructive operation; the essentials are well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a detailed description for draft_id (100% coverage), including provenance from list_posts or create_draft_post. The tool description adds no additional parameter meaning beyond referencing the id's association with published posts, which is behavior rather than parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('unpublished draft'), clearly distinguishing it from sibling tools like publish_draft or get_draft. It also adds scope ('unpublished') and explicitly states what it refuses to do, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool (delete unpublished drafts) and when not to (refuses published posts). It also provides an alternative (the dashboard) and explains the rationale, giving clear guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the key behavioral trait: by default it returns a projection of fields, and passing full: true returns all 111 fields. This goes beyond the schema by explaining the 'projection' concept and the payload implications (~24 KB, including every notification toggle and HTML content). Since it's a read-only operation, no side-effect disclosure is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that states the action, the resource, enumerates key fields, and explains the default vs. full behavior. Every element earns its place, and the most important information is front-loaded. There is zero fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with one optional parameter and no output schema, the description adequately covers the purpose, return content, and the difference between projection and full payload. It omits error handling or authentication details, but these are less critical for a simple read operation. The description is complete enough for an agent to decide on and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a detailed description of the 'full' parameter, so the baseline is 3. The tool description adds the 'projection' concept and clarifies the default behavior, which supplements the schema and gives the agent a better mental model of the parameter's effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and names the exact resource: 'settings and identity of your Substack publication'. It enumerates concrete fields (name, subdomain, custom domain, hero text, copyright, sender name, logo, plans and payment state), which clearly distinguishes it from the sibling tools that focus on drafts, posts, comments, or analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: whenever you need the publication's settings or identity. It doesn't explicitly state exclusions or alternatives, but no sibling tool serves the same purpose, so the guidance is sufficient. A 4 reflects this clear context without explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses output fields, default filtering of paused/expired, and directionality. It does not detail auth or return structure, but core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, then the exclusion and differentiation. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description covers purpose, default filters, and alternatives. Return structure is only partially specified, but given the schema covers parameters, this is adequate. A perfect score would require explicit mention of pagination or return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for both limit and active_only. The description adds context tying active_only to the exclusion behavior, but does not materially expand parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a clear resource ('Substack publications this account subscribes to') and explicitly distinguishes itself from list_subscribers by clarifying directionality. This makes the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool ('This is what the account reads') and names the alternative ('for your own subscribers use list_subscribers'). It also describes default behavior and the condition to change it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the key side effects: the post goes live, it may email subscribers, and the action is irreversible. This goes beyond the schema and gives the agent essential behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. The purpose is front-loaded, and each sentence adds a distinct piece of information: action, side effects, irreversibility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the main behavioral aspects, including irreversible consequences. It could mention the return value, but given the lack of output schema and the straightforward nature of the operation, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has complete descriptions for both parameters (100% coverage), so the baseline is 3. The description reiterates the email risk but does not add new parameter-specific details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool publishes a draft, making it live on the web, and distinguishes the optional email behavior. It also contrasts with siblings like update_draft and delete_draft by noting publishing is irreversible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context on when to use: to make a draft public, with a caution that publishing cannot be undone. It also explains that `send` should only be true when email is intended, since email cannot be recalled. This is good guidance, though it doesn't explicitly compare to alternatives beyond noting the absence of an unpublish tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it delivers meaningful disclosure: partial-update semantics, the body being untouched, and the side effect that a cover_image not already hosted by Substack is downloaded and re-hosted first. It does not cover auth/rate-limit/error behavior, but the disclosed traits go well beyond a bare mutation description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose, followed by the partial-update rule, the cover_image re-hosting behavior, and id sourcing. Every sentence earns its place; no redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter mutation tool with no annotations and no output schema, the description covers the essentials: scope of what changes, the safety-relevant partial-update behavior, a non-obvious side effect (re-hosting), and parameter provenance. The schema fills in all parameter details. The only gap is the absence of return-value/error information, which the description could have mentioned since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 genuine value beyond the per-parameter schema by stating the partial-update rule — 'only the fields you pass change' — which contextualizes all 11 optional parameters as omit-to-keep semantics. This is a meaningful addition, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Change an existing draft's title, subtitle or any of its Post settings', followed by an explicit field list. This clearly differentiates update_draft from siblings like create_draft_post, set_post_body, publish_draft, and delete_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool: it is a partial update ('only the fields you pass change'), and explicitly notes the body is left alone, which implies set_post_body is the alternative for body edits. It also tells the agent where to source the required id ('Take the id from list_posts or create_draft_post'). It stops short of explicitly naming when-not-to-use alternatives, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly discloses that the comment is public, published under your name, and that the server offers no way to delete it—critical behavioral traits that inform the agent of irreversibility and 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and resource, and the second sentence adds a crucial caveat about public visibility and non-deletion. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write tool with two parameters, no annotations, and no output schema, the description covers all essential context: the action, the target (own posts), identity ('as you'), public visibility, and irreversibility. It is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with rich descriptions for both parameters: body clarifies plain text conversion to Substack's format, and post_id references list_posts. The description itself adds no extra param semantics beyond what the schema already provides, consistent with the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Post a public comment'), the resource ('one of your posts'), and its nature ('public', 'as you'). It distinguishes itself from read-only comment tools like get_post_comments by specifying it creates a public comment on your own post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this when you want to post a public comment on your own post, under your identity. However, it does not explicitly mention alternatives or when not to use it, such as pointing to get_post_comments for reading comments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully owns behavioral disclosure. It details the asynchronous generation and waiting process, the absence of paging, and the special handling of unexportable columns via `missing_columns` rather than failure. This goes beyond typical descriptions by explaining edge cases and operational behavior, giving the agent critical context for invocation and error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence contributes meaningful information. It front-loads the primary purpose, then adds differentiators and operational details. The enumeration of engagement metrics is long but serves to differentiate from list_subscribers. It is not overly verbose for the complexity it covers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description provides essential context about return behavior: it waits asynchronously, returns parsed records, and reports missing columns. It also clarifies the full matching set and the relationship to list_subscribers. While it doesn't detail error handling or the exact record structure, the provided information is sufficient for most invocation decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with detailed descriptions for each parameter, including the full column enum with human-readable labels. The description adds value by clarifying that filters are the same as list_subscribers, the export covers the whole matching set with no paging, and the async wait behavior explains the max_wait_seconds parameter. This enhances the parameter semantics beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Export subscribers') with the full column values and distinguishes itself from the sibling list_subscribers by highlighting that it returns engagement metrics list_subscribers cannot return. The phrase 'covers the whole matching set — there is no paging' further clarifies its scope, making it unambiguous what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context by explicitly referencing list_subscribers ('Takes the same filters as list_subscribers') and contrasting the return capabilities ('engagement metrics list_subscribers can filter on but not return'). This implies when to use this tool over the alternative, though it does not explicitly state exclusions or when to prefer list_subscribers. The lack of paging and asynchronous behavior also guide usage expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It states the tool is read-only ('Read'), explains report selection, and explicitly mentions date defaults (e.g., 'default to the last 30 days'). However, it does not detail edge cases like rate limits or result format, which is acceptable given the simple read nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes only essential usage instructions and an alternative reference. Every clause earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, 1 enum, no output schema), the description covers purpose, usage, report selection, date defaults, and an alternative path. It is sufficiently complete for an agent to invoke the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 provides a high-level summary of parameter behavior ('the ones covering a period accept from_date and to_date') but does not add per-parameter meaning beyond what the schema already specifies, such as the enum values or the limit usage details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Read one publication-level analytics report,' with an explicit scope covering the dashboard's Stats tabs and a list of report types. It also distinguishes itself from a sibling by directing per-post queries to get_post_stats, ensuring no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent when to use this tool versus an alternative: 'For per-post numbers use get_post_stats instead.' It also explains how to select a report and the default date behavior, providing clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the endpoint returns UUIDs and this tool resolves them against the publication's tag list, adding meaningful context beyond a simple 'list' operation. It does not explicitly state read-only behavior, but 'List' implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The first sentence states the core functionality, and the second provides essential context about UUID resolution and why this tool is needed. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is complete. It explains what the tool does, why it exists (resolving UUIDs), and how it fits with sibling tools. The parameter is well-documented in the schema, and the output (tag names) is implicitly clear from 'by name.'
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with a clear description for post_id, so the baseline is 3. The tool description does not add extra parameter semantics beyond mentioning 'one post,' but the schema sufficiently documents the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List the tags on one post, by name,' which is a specific verb-resource pairing. It further distinguishes itself from siblings by stating it is the only way to read back what add_tag_to_post did, since neither get_draft nor list_posts carries tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool: after using add_tag_to_post, because the alternatives (get_draft, list_posts) do not include tags. This clearly guides the agent on appropriate usage and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions public visibility, appearance on profile, irreversibility, lack of deletion handle, and 404 errors for posts—comprehensive for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action, followed by essential caveats. No wasted words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter mutation with no output schema, the description covers purpose, public side effects, irreversibility, and input restrictions. It is complete and well-suited to the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already provides detailed semantics for both parameters (comment_id source/format, tab_id default). The description adds no parameter-specific information, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Restack a Note to your own followers', clearly stating the action (restack), the resource (Note), and the audience. It distinguishes from sibling tools by using 'restack' which appears nowhere else, and adds scope with 'Notes only' to exclude posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-not guidance: 'Notes only: restacking a post is not supported' and warns about irreversibility ('cannot be undone from here'). It does not name alternative tools, but the context strongly implies when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing non-obvious behaviors: the count is independent of limit (making limit=1 a segment-size probe), engagement columns can be filtered on but are not part of returned records, and filters combine with AND. It lacks explicit read-only/permission notes, but the read-style action is implied and the disclosed quirks are highly valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: purpose, feature set, count behavior, and an alternative-tool pointer. Each sentence carries distinct information with no filler or repetition. The structure front-loads the core purpose and then adds operational details in a logical order.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, nested filters with 48 columns) and the very rich schema, the description supplies enough high-level context: it explains the AND limitation, the count behavior, and the division of labor with export_subscribers. It does not enumerate the returned record fields, but the schema and the explicit exclusions make the tool usable without that detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful extra semantics: the limit parameter's use for cheap segment sizing via count, and the clarification that the filters parameter can include engagement columns even though they are not returned. These enrich the parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb-resource pair: 'List and filter the subscribers of your Substack publication.' It further distinguishes itself from sibling tools, especially export_subscribers, by explicitly noting that engagement columns are filterable here but returned only via export_subscribers. This makes the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use context: it supports dashboard-like filtering, AND-only combination, and a cheap count-based segment sizing pattern. It also provides an explicit alternative: 'use export_subscribers to read their values' for engagement metrics, clearly directing the agent away from this tool for that need.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly states this is a read-only operation ('Read') and lists the exact metrics covered. It also notes it takes no arguments. It doesn't discuss possible rate limits or time windows for 'recent,' but for a stat-read tool this is reasonably transparent. A 5 would require more detail on data freshness or pagination, but the core behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences, front-loaded with the action/scope, and every word adds value. It lists the key metrics and then directs users to the alternative without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only stats tool, the description is complete. It tells exactly what data is returned, that no arguments are needed, and where to go for deeper metrics. No output schema exists, but for this simple tool, the description sufficiently covers what the agent needs to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is vacuously 100%. The baseline for 0 params is 4; the description reinforces this by explicitly stating 'Takes no arguments,' which is helpful but adds little beyond the schema. No deduction needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and clearly identifies the resource ('your Substack publication') and the exact metrics returned (subscribers, ARR, site views, open rate). It also explicitly contrasts with the deeper get_analytics tool, distinguishing it from the most likely sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use guidance for headline stats and explicitly states when not to use it: 'For anything deeper — retention, churn, growth sources, referrals — use get_analytics.' This provides an explicit alternative, satisfying the highest bar for usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so admirably. It discloses key behaviors: server-side download for URL, direct disk read for path, refusal of private/loopback/link-local hosts, rejection of HEIC, max 10 MB, and content-based type detection. These are non-obvious and crucial for a caller to avoid errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense paragraph that front-loads the main action and then provides the two variants and constraints. Every sentence adds critical information; there is no filler. It is appropriately sized given the number of constraints and the need to distinguish the two input modes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description clearly states the return value ('get back a Substack URL'). It covers the two input modes, constraints, and the relationship to callers. The tool's complexity is moderate, but the description leaves no critical unknowns for a caller to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 tool description largely restates what the schema already says for the url and path parameters (refusal constraints, max size, HEIC). It adds the 'will actually render' tie-in, which aids purpose, but does not materially extend parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Host an image on your Substack publication and get back a Substack URL.' It clearly distinguishes this tool from siblings by noting the returned URL is exactly what image2.src in set_post_body and cover_image in update_draft will render. This is unambiguous and contextually differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use each input mode: 'url' for remote images the server downloads and re-hosts, 'path' for locally generated or edited images read directly from disk. It also ties the tool to the consuming tools (set_post_body, update_draft), making the use case evident. No alternatives are listed among siblings because none exist; the guidance is fully sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/marcomoauro/substack-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server