Publish and manage blog posts, articles, and series on Misar.Blog from your AI agent. 20 tools for publishing, analytics, newsletter, and AI-assisted content generation.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.7/5 across 23 of 23 tools scored.
The tools mostly map to clearly distinct resources and actions, with good behavioral separation between create_draft, publish_article, and update_article, and between the two title-generating tools. Some naming choices are still slightly misleading, such as get_series returning the full collection rather than a single series, and generate_cover_image references a non-existent upload_image tool.
The vast majority of tools follow a clean lowercase verb_noun pattern, including create_*, get_*, list_*, and add_* names. Notable exceptions are upgrade, a bare verb that also mixes read and mutate behaviors, and get_series, which functions more like a list than a get.
23 tools is in the heavy range for an MCP server, exceeding the ideal 3-15 span. That said, the tools do span legitimate blogging concerns such as articles, reactions, series, newsletters, analytics, and AI assistance, so the count feels broad rather than padded.
The surface covers article creation, reading, updating, and publishing, but there is no delete or unpublish for articles/drafts, no way to remove an article from a series, and no update/delete for series. The dangling reference to upload_image in generate_cover_image also suggests a missing tool, and agents will hit dead ends trying to undo publication or remove content.
add_reactionAdd a reactionARecord one reaction — like, clap, or bookmark — from the authenticated account on an article.
This acts publicly as the account holder, so only call it when the user has actually asked to react; do not react on their behalf to be helpful. Adds a single type per call — react twice for two types.
Safe to repeat: if the reaction already exists the call succeeds and changes nothing, so it will not double-count. Requires an API key. Use remove_reaction to undo, and get_reactions to see the resulting totals.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Which reaction to add: 'like' approval, 'clap' stronger approval, 'bookmark' save for later. | |
| article_id | Yes | UUID of the article to react to, from the `id` field of article tools. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavioral context beyond annotations: acts publicly as the account holder, safe to repeat without double-counting, and requires an API key. These details are not captured by annotations and are valuable for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded definition with no fluff. Each sentence serves a purpose: purpose, usage caution, idempotency, and alternative links. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with good schema and annotations, the description is complete. It covers side effects, idempotency, auth, and provides alternate tool guidance. No output schema needed, so no explanation of returns required. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters fully with descriptions, so baseline is 3. The description adds the constraint 'Adds a single type per call—react twice for two types,' which clarifies parameter usage beyond schema. No significant additional semantics for article_id beyond schema, but overall a slight boost.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: recording a reaction (like, clap, bookmark) from the authenticated account on an article. It distinguishes from siblings by explicitly naming remove_reaction and get_reactions as alternatives for undo and viewing results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: only call when user explicitly asks, not proactively. Also explains idempotency and directs to remove_reaction for undo and get_reactions for totals, clear when-to-use and when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
add_to_seriesAdd an article to a seriesAPlace an existing article into an existing series, optionally at a specific position.
Both the series and the article must already exist — this creates neither. Identify them by SLUG, not id: get_series supplies the series slug and the article tools supply the article slug. Omit position to append at the end.
Requires an API key. Adding an article does not change its publication status or URL; it only changes where it appears. Inserting at a position shifts the articles after it down. Errors if either slug is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| position | No | 1-based position within the series. Omit to append at the end. Inserting shifts later articles down. | |
| series_slug | Yes | Slug of the target series, from get_series. Not its title or id. | |
| article_slug | Yes | Slug of the article to add, from list_my_articles. Not its title or id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: it states that adding an article does not change its publication status or URL, and that inserting at a position shifts later articles down. It also notes that errors occur if either slug is unknown. The annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, and the description aligns with these without contradicting them. It could have mentioned idempotency explicitly, but the annotations cover that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It starts with a clear one-sentence summary, then provides necessary details in a logical order: prerequisites, identification method, optional parameter behavior, and side effects. Every sentence adds value without redundancy. It is front-loaded with the core purpose and then elaborates.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema), the description is complete. It covers prerequisites, parameter semantics, side effects, and error conditions. The annotations provide additional safety hints, and the schema covers parameter details. There is no missing information that would prevent an agent from using the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage with detailed descriptions for each parameter, including the 1-based position and the source of slugs. The description reinforces this by explaining the position behavior and the need to use slugs from specific tools. It adds a bit of extra context (e.g., 'Not its title or id') but mostly complements the schema. Since the schema is thorough, the description's additional value is moderate, hence a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Place an existing article into an existing series, optionally at a specific position.' It specifies the verb (place/add), the resources (article, series), and the key constraint (both must already exist). It also distinguishes from siblings like create_series and update_article by emphasizing it does not create either entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: it requires both the series and article to already exist, and it directs the user to get slugs from get_series and article tools. It also explains the optional position parameter and the behavior of omitting it (append at end). This clearly differentiates it from creation tools and provides context for when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_draftCreate a draftAInspectSave an article as an unpublished draft.
Nothing becomes visible to readers: use this whenever the work still needs review, and publish_article only when it should go live. The draft can be edited afterwards with update_article.
Each call creates a NEW draft — not idempotent, so calling twice leaves two drafts. Requires an API key. Returns the draft with an editor_url for finishing it in the browser.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Topic tags to carry through to publication. | |
| title | Yes | Working headline. Can be changed before publishing. | |
| body_markdown | Yes | Article body so far, as Markdown. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (non-idempotent, non-destructive), the description discloses the API key requirement, the fact that each call creates a new draft (elaborating on idempotentHint), and the return value including editor_url. This adds useful context beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet complete, with three short paragraphs. The main purpose is front-loaded, and every sentence adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description mentions the return format (draft with editor_url). Combined with schema and annotations, it covers purpose, usage, non-idempotency, auth, and response, making it fully contextual for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with clear descriptions for all three parameters. The tool description does not add further parameter-level meaning, 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Save an article as an unpublished draft') and clearly differentiates from siblings by contrasting with publish_article and update_article. It leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance is provided: 'use this whenever the work still needs review, and publish_article only when it should go live.' It also notes the draft can be edited with update_article, giving clear alternatives and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_seriesCreate a seriesAInspectCreate a new, empty series — a named collection that related articles can be added to.
Creating the series does not move any article into it; follow up with add_to_series for each one. Call get_series first to avoid making a second series with the same title, since each call creates a NEW series and nothing deduplicates them.
Requires an API key. The series and its URL become publicly reachable, though it shows nothing until articles are added. Returns the series with the slug that add_to_series needs.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Display name of the series. The slug is derived from this. | |
| description | No | Short summary shown on the series page. Optional. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it as write, non-idempotent, and non-destructive. The description adds valuable behavioral details: API key requirement, public reachability, lack of deduplication, and the output containing a slug. These go beyond the annotations and do not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written with no fluff. Each sentence adds essential information: purpose, usage sequence, dedup warning, API key, public visibility, and output. It is well-structured and front-loads the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with no output schema, the description covers all necessary aspects: what it does, prerequisites, side effects, and return value. It compensates for the missing output schema by explicitly stating the slug is returned for add_to_series.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are already described (title with slug derivation, optional description). The description adds no extra parameter-specific semantics beyond what the schema provides, so it meets the baseline but doesn't enhance it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new, empty series and distinguishes it from related operations like add_to_series and get_series. It explicitly notes that it does not move articles, which uniquely identifies its scope among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: call get_series first to avoid duplicates, follow up with add_to_series for each article, and requires an API key. It also mentions the returned slug is needed for add_to_series, effectively guiding the agent through the correct workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_cover_imageGenerate a cover imageAInspectGenerate an image from a text prompt with AI, upload it to the Misar.Blog CDN, and return its public URL for use as cover_image_url when publishing.
Use it when no artwork exists yet; use upload_image for a file the user already has. Each call generates a NEW image and costs generation credits against the account's plan — it is not idempotent, so re-running to 'try again' bills again. Generation takes noticeably longer than other tools.
Requires an API key. The resulting URL is public and cannot be deleted through this server. Results vary between runs for the same prompt.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Output dimensions: '1792x1024' landscape (the default, best for article covers), '1024x1024' square, '1024x1792' portrait. | 1792x1024 |
| prompt | Yes | What the image should show, in plain language, up to 1000 characters. Describe subject and style; avoid asking for text in the image. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: generation credits, non-idempotence, longer execution time, API key requirement, public URL irreversibility, and output variability. No contradiction with annotations (idempotentHint=false aligns with 'not idempotent').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence delivers critical information: purpose, when to use, costs, timing, API key, deletion limitations, and variability. No redundancy or filler, well-organized with key facts front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description explains the return value (public URL for cover_image_url) and covers all relevant operational aspects (credits, API key, side effects). 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by advising 'Describe subject and style; avoid asking for text in the image' and clarifies size usage (best for article covers), which enriches prompt and size semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Generate an image from a text prompt with AI, upload it to the Misar.Blog CDN, and return its public URL for use as cover_image_url when publishing.' This specific verb+resource combination distinguishes it from sibling tools like upload_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use it when no artwork exists yet; use upload_image for a file the user already has.' It also warns about non-idempotent behavior and costs, providing clear context for when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_title_seoGenerate SEO titles from keywordsAGenerate 5 search-optimised article titles from a TOPIC OR KEYWORD, each with a keyword-strategy hint. Aims at high-volume, low-competition long-tail phrases and at AI answer engines (ChatGPT, Perplexity, Claude) as well as Google.
Pick between the two title tools by what you have in hand: use this one when you have a topic or keywords and the article may not be written yet. Use suggest_titles when the draft already exists and you want titles drawn from its actual text. Passing context here does not make them equivalent — this one still optimises for the keywords you supply.
Nothing is saved and no article is created or retitled; use update_article to apply a title. Requires an API key and consumes AI credits per call. Generative, so repeated calls return different titles.
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Topic or target keywords, 3-500 characters. Include niche, audience and any long-tail phrase you want to rank for, e.g. 'best AI writing tools for beginner bloggers 2025'. | |
| context | No | Optional draft text (plain or Markdown, up to 8000 chars) so the titles match what the article actually says. Titles still follow `prompt` for keywords. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=true, destructiveHint=false, and idempotentHint=false. Description adds that nothing is saved or created, requires API key and consumes credits, and is generative (non-deterministic). This adds behavioral context beyond annotations, though the annotation already signals read-only and non-destructive. The API key and credit consumption details are helpful extras.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single paragraph, front-loaded with purpose, then usage guidance, then side effects and permissions. Every sentence adds useful information without redundancy. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (generative, two parameters, no output schema), the description covers purpose, usage alternatives, side effects, and parameter roles. The absence of an output schema is not a gap since the description specifies it returns titles with hints. It also mentions API key requirement and non-determinism, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema descriptions are informative (e.g., what to include in prompt, context limits). However, the description adds context about how the parameters interact (context does not override prompt) and clarifies the optimization goal for AI answer engines. This adds value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states what it does: 'Generate 5 search-optimised article titles from a TOPIC OR KEYWORD'. The verb 'generate' and resource 'article titles' are specific likely, and it explicitly distinguishes from suggest_titles by noting the difference in input (topic/keyword vs existing draft).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use this tool: when you have a topic or keywords and the article may not be written yet, and when not to (use suggest_titles for existing drafts). Also clarifies that passing context does not make them equivalent, giving clear disambiguation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_analytics_summaryGet analytics summaryASummarise the account's performance over a trailing window: page views, gross and net revenue, and active subscriber count.
Use it for 'how did I do this month' style questions. These are whole-account totals — it cannot break results down per article, and it covers a trailing window ending today rather than an arbitrary date range.
Reads only. Requires an API key. Revenue is returned in cents (revenue_cents gross, revenue_net_cents after fees) with a formatted revenue_usd added for convenience — read the cents fields when doing arithmetic. Zero views is a real answer, not an error.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Size of the trailing window in days, ending today. 1-365, defaults to 30. Use 7 for a week, 365 for a year. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide read-only, idempotent, non-destructive hints, and the description adds valuable context: requires an API key, revenue is returned in cents (revenue_cents, revenue_net_cents) plus a formatted revenue_usd, and zero views is a real answer rather than an error. This exceeds the annotation baseline and enriches agent understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into three tight paragraphs: definition, usage context, and behavioral/unit details. Every sentence contributes unique value with no filler or repetition, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter, read-only tool with no output schema, the description is remarkably complete. It specifies return metrics, units, auth requirements, and edge-case handling (zero views), leaving the agent fully informed about invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'days' has a full schema description covering range, default, and examples, so schema coverage is 100%. The tool description reinforces the trailing-window and ending-today semantics but does not add new parameter-specific information beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'summarise' and the resource 'account's performance', enumerating specific metrics: page views, gross and net revenue, and active subscriber count. It distinguishes itself from per-article analytics by explicitly noting it cannot break results down per article, making it distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides a usage scenario ('how did I do this month' style questions) and clear exclusions (no per-article breakdown, no arbitrary date range). However, it does not name any alternative sibling tools, so the guidance falls just short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_articleGet one articleAFetch a single article by slug, including its full Markdown body.
Use this after list_my_articles or search_articles has given you a slug and you need the actual content — for reading, editing, or repurposing it. Fetching one article at a time is deliberate: the listing tools omit bodies so they stay cheap.
Reads only; nothing is created or modified. Requires an API key for unpublished articles; published ones are readable without. Returns the article object with content_markdown populated. Errors if the slug does not exist or the account cannot see it.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | URL slug of the article, e.g. 'how-we-cut-build-times'. Not the numeric id, and not the full URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this with 'Reads only; nothing is created or modified' and adds additional context: API key requirement for unpublished articles, error behavior for non-existent/inaccessible slugs, and that it returns an article object with content_markdown populated. This exceeds what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main purpose, then usage context, then additional behavioral details. Each sentence contributes value without redundancy, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and comprehensive annotations, the description covers all necessary context: what it returns, when to use it, auth requirements, and error conditions. The presence of an output schema is not marked, but the description explicitly mentions the returned object and its field, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'slug' is fully documented in the JSON schema (100% coverage) with a clear description, example, and exclusions. The description adds no extra parameter-specific information, but the schema is sufficient, 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a single article by slug, including its full Markdown body. It distinguishes from sibling tools like list_my_articles and search_articles, which omit bodies, so the purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this after list_my_articles or search_articles has given you a slug and you need the actual content' and explains why fetching one at a time is deliberate. This clearly indicates when to use and differentiates from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_follow_statusGet follow statusACheck whether the authenticated account follows a given profile, and how many followers that profile has.
Use it before offering to follow someone, so you do not suggest an action that is already done. It answers about ONE profile identified by UUID — there is no tool here that lists everyone you follow.
Reads only; following state is not changed. Requires an API key and counts against the plan's request quota. Returns the follow relationship and follower count. Errors if the UUID does not match a profile.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | UUID of the profile to check, as returned in author fields by article tools. Not the username. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful context beyond annotations: quota impact ('counts against the plan's request quota'), auth requirement ('Requires an API key'), error behavior ('Errors if the UUID does not match a profile'), and return shape ('Returns the follow relationship and follower count'). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the core purpose, then usage guidance, then behavioral details. Zero fluff — every sentence contributes (purpose, when-to-use, read-only/quota, return/error). Well-structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with strong annotations (readOnly, idempotent, non-destructive), 100% schema coverage, and no output schema needed, the description is complete: purpose, usage context, auth/quota costs, return shape, and error behavior are all covered. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already thoroughly documents user_id ('UUID of the profile to check, as returned in author fields by article tools. Not the username.'). The description slightly reinforces single-profile semantics ('answers about ONE profile identified by UUID') but adds no new syntax or format details beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description leads with a specific verb+resource: 'Check whether the authenticated account follows a given profile, and how many followers that profile has.' It clearly states the scope (ONE profile by UUID), and there is no competing follow-status tool among the 23 siblings, so it distinguishes itself by being the sole profile-follow-status query tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use it: 'Use it before offering to follow someone, so you do not suggest an action that is already done.' It also provides a notable exclusion: 'there is no tool here that lists everyone you follow,' which prevents the agent from searching for a nonexistent list capability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_profileGet my profileAFetch the authenticated account's own creator profile: id, username, display name, bio, public profile URL, and whether Stripe payouts are connected.
Use it to confirm which account a key belongs to before acting on that account's behalf, to get your own profile id for tools that take a UUID, or to check stripe_connected before discussing paid posts. It only ever describes the caller — there is no tool here for looking up someone else's profile.
Reads only; nothing is modified. Requires an API key, and takes no parameters. Errors if the key is missing or invalid, which is the quickest way to test authentication.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds context about requiring an API key, error behavior if key is invalid, and that it never describes other users. This goes beyond annotations, though the safety profile is already clear. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each dense with useful info: action, specific fields, use cases, exclusions, auth requirement. No fluff; every sentence earns its place. Front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description covers all essential aspects: what it returns (profile fields), when to use it, limitations (only caller), authentication, and error conditions. For a simple tool, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters)Skip to content. The description explicitly states 'takes no parameters', which is clear and sufficient. With 0 params, baseline is 4 and the mention supports it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches the authenticated account's own creator profile, listing specific fields (id, username, display name, bio, URL, stripe_connected). It distinguishes itself from siblings by explicitly noting there is no tool for looking up others' profiles, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: confirming key ownership, retrieving profile ID for other tools, checking stripe_connected before discussing paid posts. Also states exclusions: 'no tool here for looking up someone else's profile', which guides tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_reactionsGet article reactionsARead the reaction totals on one article, plus which reactions the authenticated account has left on it.
Use it before add_reaction or remove_reaction so you know the current state — it is how you tell 'not yet liked' from 'already liked'. Covers one article at a time.
Reads only; no reaction is added or removed. Requires an API key. Returns counts per type (like, clap, bookmark) alongside the caller's own reactions. Zero counts are a real answer, not an error.
| Name | Required | Description | Default |
|---|---|---|---|
| article_id | Yes | UUID of the article, from the `id` field returned by article tools. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint=true and destructiveHint=false, the description reinforces the read-only nature and adds context: it does not add or remove reactions, requires an API key, returns counts per type, and clarifies that zero counts are valid (not errors). This goes beyond the annotations, though it doesn't cover all edge cases like 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three short paragraphs, each serving a purpose: definition, usage guidance, and behavioral clarity. It is front-loaded with the core purpose, but the third paragraph could be slightly more compact, hence a 4 rather than 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input (one parameter) and the existence of annotations, the description covers the key aspects: what it does, when to use it, its read-only nature, and output contents. It might mention error handling or response format in more detail, but for this complexity level, it is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter semantics are fully defined in the schema. The description only implies that the parameter is an article ID from article tools, but does not add meaningful new information beyond the schema, 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads reaction totals and the authenticated account's reactions on one article, distinguishing it from mutation tools like add_reaction and remove_reaction. The scope (one article at a time) and the verb 'read' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent to use this tool before add_reaction or remove_reaction to know the current state, and contrasts it with those tools. It also notes the single-article limitation, which helps decide when to use it versus other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_seriesList my seriesAList every series the authenticated account owns. Despite the name this returns the whole collection, not one series — there is no single-series lookup.
Use it to find a series slug before calling add_to_series, or to check whether a series already exists before create_series makes a duplicate.
Reads only; nothing is created or modified. Requires an API key, and takes no parameters — it is unfiltered and unpaginated. Returns { series, total } where each entry carries id, slug, title, description, url and article_count. An empty list means the account has no series yet, which is not an error.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint true, but the description adds crucial behavioral details beyond that: it notes API key requirement, no parameters, unfiltered and unpaginated behavior, return shape ({ series, total } with specific fields), and that an empty list is valid, not an error. This fully discloses side effects and expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet packed with information, structured in short paragraphs. The first sentence states purpose, the second covers usage, and the third details behavior and return format. Every sentence adds unique value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list-all tool with no parameters, the description covers all necessary context: authentication, return shape with field names, handling of empty results, and typical use cases. It is complete without needing an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the baseline is 4. The description reinforces the absence of parameters and clarifies the unfiltered/unpaginated nature, adding context that is essential for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every series owned by the authenticated account, and explicitly clarifies that despite the name it returns the whole collection, not a single series. This distinguishes it from sibling tools like get_article and list_my_articles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit, actionable usage guidance: use it to find a series slug before calling add_to_series, or to check for duplicates before create_series. These alternatives are named and the context is clear, making the when-to-use unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_commentsList article commentsARead the comment thread on one article, oldest first, paginated.
Use it to review reader feedback or summarise a discussion. It reads comments only; there is no tool here for posting or moderating a reply.
Reads only. Requires an API key and counts against the plan's request quota. Page through with limit and offset — the default returns the first 20. Returns the comments with their authors and timestamps; an empty list simply means no comments yet, which is not an error.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Comments per page, 1-100. Defaults to 20. | |
| offset | No | Comments to skip before this page. Defaults to 0. | |
| article_id | Yes | UUID of the article, as returned in the `id` field by article tools. Not the slug. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to state read-only behavior. It adds real value by mentioning the API key requirement and request quota usage, and by clarifying that an empty list is not an error. This goes beyond annotation-provided facts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each packed with essential information. It is front-loaded with the core purpose, then adds usage context, limitations, and behavior. No wasted words or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description adequately explains the return values (comments with authors and timestamps) and handles the edge case of an empty list. Combined with annotations that cover safety, this is complete for a simple read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by specifying the sort order ('oldest first') and that pagination uses limit/offset with a default of 20. It also mentions the returned fields (authors, timestamps), which the schema does not. These additions justify a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the comment thread for a single article, sorted oldest first and paginated. It distinguishes itself from siblings like get_reactions (which handles reactions) and list_my_articles (which lists user's own articles). The verb 'read' and the resource 'comment thread' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it ('to review reader feedback or summarise a discussion') and what it does not do ('no tool here for posting or moderating a reply'), providing clear exclusions. However, it does not explicitly name alternative tools for those actions, so I deduct slightly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_my_articlesList my articlesAList articles owned by the authenticated account, newest first, including drafts and scheduled posts.
Use this to find your own work — it is the only listing that sees unpublished content. To search across the whole site, including other creators, use search_articles instead.
Reads only; nothing is created or modified. Requires an API key. Returns { articles, total }, where each article carries id, slug, title, status, url, editor_url, tags and timestamps, but NOT the article body — call get_article for that. total counts all matches, not just the page returned.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum articles to return, 1-100. Defaults to 20. | |
| status | No | Return only articles in this state. Omit to return every state the account owns. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context beyond these: it states 'Reads only; nothing is created or modified' (reinforcing safety), requires API key, describes returns as { articles, total }, and clarifies that the article body is not included. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with front-loaded core purposeasi. The first sentence states the exact action and scope; subsequent sentences add alternative guidance and return format without fluff. Zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explicitly lists the returned fields (id, title, status, etc.) and notes the body is excluded alerting the agent to not expect content. Auth, scope, and sibling distinction are all covered. It is fully self-sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters (limit and status) with clear descriptions, including bounds and optionality. The description adds nothing new about parameter semantics; it does hint at pagination via 'total counts all matches' but that's output, not parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('List articles owned by the authenticated account') and immediately clarifies scope (unpublished content included) and ordering (newest first). Explicitly differentiates from the sibling search_articles by stating it is the only listing that sees unpublished content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use context ('Use this to find your own work') and an explicit alternative ('To search across the whole site, use search_articles instead'). This makes the selection unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_newsletter_issuesList newsletter issuesAList newsletter issues the account has sent or scheduled, newest first.
Use it to check what went out and when, or to confirm a scheduled send exists before queueing another. For WHO receives them, use list_newsletter_subscribers.
Reads only — this neither sends nor cancels an issue. Requires an API key. Returns each issue with its subject, status and send time. An empty list means nothing has been sent yet, which is not an error.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Issues to return, 1-50, newest first. Defaults to 10. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds value by stating 'Reads only — this neither sends nor cancels an issue' (behavioral confirmation), noting the API key requirement (auth context), previewing return fields (subject, status, send time), and explaining the empty-list edge case semantics ('not an error'). No contradiction with annotations. Genuinely useful context beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place: purpose, use cases + alternative, read-only clarification with auth note, and empty-list semantics. The most critical information (core purpose and ordering) is front-loaded, and every subsequent sentence adds non-redundant value. Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with 1 optional parameter, no output schema, and rich annotations, the description is fully complete. It covers return value semantics (subject, status, send time) despite lacking a structured output schema, explains error/empty behavior, and addresses the sibling relationship. The complexity is low, and the description fully matches that complexity budget.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single parameter (limit) is already well-documented in the schema with range, default, and ordering semantics. Per the baseline rule, a 3 is appropriate since the description doesn't need to compensate for schema gaps, and it doesn't contradict the schema. The description adds no param-specific detail beyond what the schema already provides, but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope construction ('List newsletter issues the account has sent or scheduled, newest first'), which precisely defines what the tool does. It explicitly distinguishes itself from the sibling tool list_newsletter_subscribers by clarifying the WHO/WHAT boundary, directly addressing the sibling context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use scenarios ('check what went out and when, or to confirm a scheduled send exists before queueing another') and names the alternative tool for a different use case ('For WHO receives them, use list_newsletter_subscribers'). This is an exemplary explicit-when-and-alternatives pattern with no ambiguity left for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_newsletter_subscribersList newsletter subscribersAList the people subscribed to the authenticated account's newsletter, paginated.
Use it to size the audience or export the list. For what has been SENT to them, use list_newsletter_issues instead.
Reads only — no email is sent and no subscriber is added or removed. Requires an API key. This returns personal data (email addresses), so treat the result as confidential and do not echo it into shared transcripts. Page with limit and offset; the default returns the first 20.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Subscribers per page, 1-100. Defaults to 20. | |
| offset | No | Subscribers to skip before this page. Defaults to 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context about requiring an API key, returning personal data (email addresses) and advising confidentiality, which goes beyond annotations. It also clarifies no email is sent and no subscriber is added/removed, reinforcing the read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and every sentence adds value. It covers usage, safety, data sensitivity, and pagination in a compact form without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no nested objects), the description is complete. It covers purpose, usage, safety, and data sensitivity. The only minor gap is not describing the return format, but since there is no output schema, the description could have mentioned what fields are returned, but it's not critical for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (limit and offset) with defaults and ranges. The description adds minimal extra meaning beyond mentioning pagination and default first 20, which is already in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists newsletter subscribers for the authenticated account, with pagination. It distinguishes itself from the sibling tool list_newsletter_issues by explicitly noting the difference between subscribers and sent issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool (to size audience or export list) and when not to (for sent content, use list_newsletter_issues). Also mentions pagination with limit and offset, and the default behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
publish_articlePublish an articleAInspectCreate a new article and make it live immediately, or schedule it for a future time.
This PUBLISHES: without schedule_at the article is world-readable the moment this returns, at the visibility you choose. If the piece is not ready, use create_draft instead and publish later. Each call creates a NEW article — it is not idempotent, so calling twice publishes twice; use update_article to change one that exists.
Requires an API key and consumes one publish from the account's plan quota; the response warns when the allowance is nearly spent. Returns the created article with its public url and editor_url.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Up to 10 topic tags used for discovery and filtering. | |
| title | Yes | Headline, 1-250 characters. | |
| visibility | No | Audience: 'public' anyone, 'subscribers' newsletter subscribers, 'paid' paying members, 'private' only you. Defaults to 'public'. | public |
| schedule_at | No | ISO 8601 timestamp to publish at, e.g. '2026-09-01T09:00:00Z'. Omit to publish immediately. A past timestamp publishes immediately. | |
| body_markdown | Yes | Complete article body as Markdown. Images may be referenced by URL. | |
| cover_image_url | No | Absolute URL of the hero image. generate_cover_image returns a URL suitable here. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations by revealing critical behavioral details: the article is 'world-readable the moment this returns' (timing of side effect), it's explicitly 'not idempotent, so calling twice publishes twice' (confirming the idempotentHint:false annotation with practical context), and it 'consumes one publish from the account's plan quota; the response warns when the allowance is nearly spent.' It also reveals the vision visibility semantics and the need for an API key. This enriches the spartan annotation data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise, self-contained sentences. The description is front-loaded with the core purpose, then adds exclusions/directives, then clarifies non-obvious behavioral facts (non-idempotent, quota), and finishes with return value details. Every clause pulls its weight; the structure is a model of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no output schema, yet the description covers the critical gaps: side effects (what gets published), auth requirements (API key), resource consumption (quota), warning behavior, and the return value shape with 'public url and editor_url.' The only thing left to the schema is parameter format validation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 100%, the baseline is already 3 because the schema documents each parameter. The description adds a bit of semantic linkage beyond what the schema states: the interaction between schedule_at and the immediate-world-readable behavior ('without schedule_at the article is world-readable... at the visibility you choose'). It doesn't add new parameter syntax, but the linkage of the scheduling/visibility/readiness concepts provides extra value, so a 4 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'Create a new article and make it live immediately, or schedule it for a future time.' It clearly differentiates the publish action with immediate vs. scheduled behavior and the mention of sibling tools (create_draft, update_article) places this tool within its family. The rest of the description enriches with publishing specifics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit alternatives are given: 'If the piece is not ready, use create_draft instead and publish later' and 'use update_article to change one that exists.' This is the gold standard for guidance on when NOT to use the tool, disambiguating it from siblings in the same domain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
remove_reactionRemove a reactionAWithdraw one reaction the authenticated account previously left on an article.
Removes exactly the type you name and leaves the account's other reactions on that article intact — removing 'like' does not remove a 'bookmark'. Nothing else is deleted: the article and its comments are untouched.
Safe to repeat: removing a reaction that is not there succeeds and changes nothing. Requires an API key. Call get_reactions first if you need to know what is currently set.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Which reaction to withdraw: 'like', 'clap', or 'bookmark'. | |
| article_id | Yes | UUID of the article to un-react to, from the `id` field of article tools. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint and destructiveHint, and the description aligns with these by stating 'Safe to repeat.' It adds value beyond annotations by detailing the exact scope of deletion ('Nothing else is deleted: the article and its comments are untouched'), the fact that removing one type doesn't affect others, and the API key requirement. This gives a fuller behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise paragraphs, front-loaded with the primary action, then expanding into edge-case behavior and usage hints. Every sentence adds value: no fluff, no repetition of schema details, and the structure is logical (action, scope, safety, prerequisite).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two simple parameters and no output schema, the description covers all essential aspects: what it does, what it doesn't affect, idempotency, authentication requirement, and a recommendation to check current state. It sufficiently prepares an agent to use the tool correctly without needing additional implicit knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clear descriptions for both parameters (type enum and article_id UUID). The description's mention of 'Removes exactly the type you name' reinforces but does not add new semantic meaning beyond the schema. Since the schema already documents the parameters thoroughly, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Withdraw one reaction the authenticated account previously left on an article.' It specifies the resource (reaction) and the exact scope (one reaction), and distinguishes from sibling tools like add_reaction and get_reactions by explicitly noting it removes only the named type and leaves others intact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (to withdraw a reaction) and gives an alternative: 'Call get_reactions first if you need to know what is currently set.' It also implies when not to use it (e.g., for adding reactions, use add_reaction, though this isn't explicitly stated but is inferable from sibling names).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
research_topicResearch a topicAResearch a topic with AI and return insights, sources, and a suggested content outline.
Use it at the START of a piece, before drafting — it produces raw material to write from, not a finished article and not a title. For titles use generate_title_seo; to see what already exists on Misar.Blog use search_articles.
Nothing is saved: no draft, article, or file is created, and calling it has no effect on the blog. Requires an API key and consumes AI credits from the account's plan, so each call costs whether or not you use the output. Runs noticeably longer than a plain read, and being generative, two identical calls give different text. Returns prose to read, not structured JSON — verify any factual claims it makes.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The topic or question to research, 5-500 characters. Specific beats broad: 'how small SaaS teams price annual plans' returns more than 'pricing'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already supply readOnlyHint=true and destructiveHint=false, but the description adds far richer behavioral context: cost implications (consumes AI credits regardless of usage), slower runtime, non-determinism (two identical calls give different text, consistent with idempotentHint=false), no persistence, and prose output requiring verification. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The ~100-word description is dense but every sentence earns its place: purpose, usage timing, alternatives, side effects, cost, non-determinism, and output format. It is front-loaded with the core purpose and each subsequent sentence addresses a legitimate concern for a generative, costly tool. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 1-parameter generative tool with no output schema, the description is complete: it explains what is returned (insights, sources, outline; prose not JSON), when to run it, what it does not do, its cost and non-determinism, and advises verifying factual claims. The absence of an output schema is compensated by the description covering return format and reliability caveats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'query' parameter is already well documented in the schema, including a specificity tip. Per the rubric, high coverage sets a baseline of 3. The description adds minimal parameter-level meaning beyond what the schema provides, so the baseline stands.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+outcome: 'Research a topic with AI and return insights, sources, and a suggested content outline.' It clearly differentiates from siblings by explicitly naming generate_title_seo (for titles) and search_articles (for existing content), making the tool's scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance ('Use it at the START of a piece, before drafting') and what it is NOT for ('not a finished article and not a title'), plus named alternatives for those cases. This is exactly the level of usage direction the rubric demands.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_articlesSearch published articlesASearch PUBLISHED articles across all of Misar.Blog, including other creators' work.
Use this for discovery, research, and competitive reading. It never returns drafts, scheduled, or private posts — not even your own — so reach for list_my_articles when you want your unpublished work.
Reads only. No API key required; unauthenticated callers are rate-limited by IP. Filters combine with AND. Returns an array of article summaries without bodies; pass a slug to get_article for the full text. An empty array means no matches, which is not an error.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text query matched against title and body. Minimum 2 characters. | |
| tag | No | Restrict to articles carrying this exact tag. | |
| limit | No | Maximum results to return, 1-20. Defaults to 10. | |
| author | No | Restrict to one author, by username. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds behaviorally meaningful details: no API key required, IP-based rate limiting for unauthenticated callers, AND-combination of filters, return of summaries without bodies, and empty array as a non-error signal. This goes well beyond what annotations and schema provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense: first sentence sets scope, second establishes use case, third handles exclusions and edge behavior, fourth covers technical details. Every sentence earns its place with no padding or redundant restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite not having an output schema, the description discloses return shape (array of article summaries), absence of bodies, and empty-array semantics. Combined with 100% schema coverage, the tool is fully specified for querying, filtering, and understanding results, making for complete contextual coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining that filters combine with AND, which clarifies interaction between q, tag, and author – a semantic not present in the schema property descriptions. This pushes the score slightly above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Search PUBLISHED articles across all of Misar.Blog, including other creators' work' – a specific verb, resource, and scope that leaves no ambiguity. It also clearly distinguishes itself from list_my_articles by stating what it never returns, providing strong sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names use cases ('discovery, research, and competitive reading') and gives a concrete alternative: 'reach for list_my_articles when you want your unpublished work.' Also directs users to get_article for full text, which provides clear guidance on when to use which tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suggest_titlesSuggest titles from draft textAGenerate 5 title options FROM AN EXISTING DRAFT, derived from what the article actually says.
Pick between the two title tools by what you have in hand: use this one when the text exists and should drive the headline. Use generate_title_seo when you are starting from a topic or keyword, or want titles aimed at specific search terms — this tool takes no keyword input at all.
Nothing is saved and the article is not retitled; apply a choice with update_article. Requires an API key and consumes AI credits per call. Generative, so repeated calls return different titles. Needs at least 20 characters of text to work from.
| Name | Required | Description | Default |
|---|---|---|---|
| context | Yes | The article text to draw titles from, plain or Markdown, 20-8000 characters. More of the real draft yields better-fitting titles than a summary. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: nothing is saved, article not retitled, requires API key and consumes AI credits, generative so repeated calls differ, needs 20+ characters. Complements readOnlyHint and idempotentHint=false without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with core purpose, followed by tool-selection guidance, side effects, and requirements. Every sentence earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is complete: covers behavior, side effects, prerequisites (API key, credits, minimum text), and output count (5 titles). Also addresses lifecycle (not applied automatically).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, but description adds useful quality guidance: 'More of the real draft yields better-fitting titles than a summary.' This goes beyond schema's basic min/max constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it generates 5 title options from an existing draft, derived from what the article actually says. Explicitly distinguishes from generate_title_seo by emphasizing draft-based vs keyword-based input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use this tool versus generate_title_seo based on what the user has in hand. Also notes that a choice can be applied via update_article, giving concrete next steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_articleUpdate an articleAChange the title, body, or tags of an article or draft that already exists.
Only the fields you pass are touched; omitted fields keep their current values. Passing tags REPLACES the whole tag list rather than adding to it, so send the full set you want. Editing a published article changes what readers see immediately; it does not unpublish or re-date it.
Safe to repeat: the same call twice leaves the same result. Requires an API key, and the account must own the article. Errors if no updatable field is supplied. Returns the updated article.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Article or draft id from a listing tool. This is the id, not the slug. | |
| tags | No | Replacement tag list, up to 10. Overwrites the existing tags entirely. | |
| title | No | Replacement headline. | |
| body_markdown | No | Replacement body as Markdown. Replaces the whole body, not a patch. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description details partial update behavior, full tag replacement, immediate publishing effect, idempotency statement, auth requirements, and error condition. It also notes what happens to omitted fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but information-denseched. Each sentence conveys a distinct and necessary fact: scope, partial update behavior, tag replacement, publication effect, auth/error, and return value. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's purpose, side effects, requirements, and expected result. With no output schema, the description explicitly mentions 'Returns the updated article' and error cases, making it complete. The annotations align with the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters are documented in the schema with 100% coverage. The description further elaborates on semantics: `tags` REPLACES the list, `body` replaces the whole body, `title` is a simple changeeur. The schema also includes `additionalProperties: false`, ensuring no unknown params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Change the title, body, or tags of an article or draft that already exists.' It specifies the resource (article/draft) and the action (change), and distinguishes it from sibling tools like create_draft and publish_article by emphasizing existing content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Only the fields you pass are touched; omitted fields keep their current values' clarifies partial updates; 'Passing `tags` REPLACES the whole tag list' warns about replacement semantics; 'Editing a published article changes what readers see immediately' informs about immediate effect; and 'Requires an API key... Errors if no updatable field is supplied' sets prerequisites and failure conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
upgradeShow plan and quota, or upgradeAShow the account's current plan, how much of each quota remains, and what a higher plan unlocks.
Called with no arguments it only reads — useful any time, not just after hitting a limit, and the natural follow-up when a write tool reports a quota error. Two arguments make it act rather than report, so pass them only on explicit instruction from the user: start_trial ENROLS the account in the free trial immediately (a real account change, not a preview), and open LAUNCHES a checkout page in the user's browser. Neither charges a card by itself.
Requires an API key. No billing state changes unless you pass start_trial; the returned quota snapshot already reflects a trial started in the same call. For whether you are authenticated at all, use status.
| Name | Required | Description | Default |
|---|---|---|---|
| open | No | Open the checkout page in the user's default browser. Side effect on their desktop — only when they asked to upgrade. | |
| plan | No | Plan slug to open, e.g. 'pro' or 'business'. Defaults to the recommended plan. Only meaningful with open=true. | |
| start_trial | No | Enrol in the free no-card trial now, if eligible. This changes the account's plan — do not set it speculatively. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that start_trial changes the account plan, open launches a checkout page, and neither charges a card. Also notes that no billing changes occur unless start_trial is passed, and mentions API key requirement. Adds specificity beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy but well-structured in three paragraphs, each addressing a distinct aspect (purpose, usage, side effects). No redundancy, but could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary context: when to use, side effects, required authentication, and no output schema needed. No gaps detected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Each parameter (open, plan, start_trial) is explained in the description with side effects and defaults. The input schema descriptions are reinforced, and additional behavioral context is provided (e.g., 'real account change').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the dual purpose: showing plan/quota and performing upgrades when specific arguments are provided. It distinguishes from sibling tools focused on content creation or management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use the read-only mode (anytime) and when to use the action mode (only on explicit user instruction). Provides context as a natural follow-up after quota errors, and warns against unsolicited use of start_trial and open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
