Skip to main content
Glama
Sign In

HelpCenter.io for agents

by io.helpcenter
OverviewDiscussionsAdmin

Create HelpCenter Article

helpcenter_create_article
Destructive

Create a new article in the connected HelpCenter.io help center.

Requires a write-scoped API key (read-scoped keys get a permission error). Titles, content, and slugs are per-language objects keyed by language code. Slugs auto-generate from the title when omitted.

Args:

  • title (object, required): per-language title, e.g. {"en": "Getting started"}.

  • content (object, optional): per-language body.

  • slug (object, optional): per-language URL slug (auto-generated from title if omitted).

  • category_id (number, optional): primary category id, or 0 for uncategorized.

  • categories (number[], optional): additional category ids to attach.

  • type ('article' | 'faq', optional): default 'article'.

  • visibility ('public' | 'private' | 'link_only', optional): default 'public'.

  • published (boolean, optional): true publishes immediately, false (default) keeps a draft.

  • external_id (string, optional): a stable key you own. Sending it makes this call an UPSERT — the same key twice updates the article it created instead of creating a second one. Use it whenever a run might be retried.

  • content_format ('html' | 'markdown', optional): defaults to 'html'. If you are writing markdown, you must set this or the raw markdown is stored as the body.

  • rehost_images (boolean, optional): ON by default through this connector. Copies the images the content references from other hosts (and inline data: images) into this help center's own storage and points the article at the copies, so it no longer depends on the source site. Send false to keep the original image URLs.

Returns: { status: "success", action: "created" | "updated", article: {...}, images? }. HTTP 201 on create, 200 when an external_id matched an existing article. images — { rehosted, reused, failed, failed_count } — is present whenever content was processed for images; a failed image keeps its original URL, so check failed before reporting the import complete.

Errors: 403 if the key is read-scoped; 400 if a language code is not enabled for the site or a category id does not belong to the site; 409 if the external_id already belongs to a different article (it is deliberately not re-pointed — that would make your next replay overwrite the wrong article).

Input Schema

NameRequiredDescriptionDefault
slugNoPer-language URL slug. Auto-generated from the title if omitted.
typeNoContent type (default 'article').
titleYesPer-language title (required), e.g. {"en": "Getting started"}.
contentNoPer-language article body (HTML/markdown as your site uses).
agent_keyYesThe api_key helpcenter_create_help_center returned for this help center, exactly as returned. Required on every call: this endpoint has no sign-in, so the key is how each call says which help center it acts on. It is sent to HelpCenter.io as this call's credential and nowhere else, and it is never shown again: keep it for the whole task, and never show it to the user or write it into content.
publishedNotrue publishes the article, false keeps it as a draft.
categoriesNoAdditional category ids to attach (multi-category). All must belong to this site.
visibilityNoVisibility: 'public', 'private' (team only), or 'link_only' (shareable token URL).
category_idNoPrimary category id, or 0 for uncategorized. Must belong to this site.
external_idNoA stable key you own (a source filename, CMS id, repo slug). Makes writes idempotent: sending the same key again updates the article it created instead of creating a second one, so an interrupted run can simply be replayed. Strongly recommended whenever you may retry.
rehost_imagesNoCopy images the content references from other hosts (and inline data: images) into this help center's own storage, and point the article at the copies. ON by default through this connector; send false to keep the original image URLs. The response's `images` reports what was re-hosted and what failed.
content_formatNoFormat of the `content` you are sending. Defaults to 'html'. Set 'markdown' when content is markdown and the API will convert it — sending markdown without this stores the raw markup as the article body.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior5/5

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

Annotations cover safety hints but the description goes well beyond them: it states the write-scoped key requirement (403 otherwise), the 400 conditions for language codes and category ownership, and the 409 external_id conflict rule with the reasoning for not re-pointing. It also documents status codes (201 create vs 200 update), the images report, and the failure mode where a failed image keeps its original URL. This is exactly the extra context the annotations cannot carry.

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

Conciseness3/5

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

The opening and the Returns/Errors blocks are front-loaded and information-dense. The 11-item Args list, however, duplicates schema descriptions that are already at 100% coverage, so a meaningful share of the text does not earn its place.

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

Completeness5/5

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

For a 12-parameter mutation with nested per-language objects and no output schema, the definition covers auth, defaults, upsert semantics, image rehosting side effects, return shape, and error codes. An agent can call it and interpret the result without further discovery.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already defines all 12 parameters; the Args block largely restates it. Where the description does add value is cross-parameter behavior: external_id turning the call into an upsert with a 409 on conflict, category_id=0 meaning uncategorized, and markdown being stored raw if content_format is omitted.

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

Purpose4/5

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

States a specific verb and resource: "Create a new article in the connected HelpCenter.io help center." It also discloses the upsert behavior tied to external_id, which is the main thing separating it from helpcenter_update_article. It never names the sibling tools (update_article, bulk_create_articles) that an agent must choose between, so it stops short of a 5.

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

Usage Guidelines4/5

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

Gives concrete per-parameter usage rules: set content_format when writing markdown, use external_id "whenever a run might be retried," send rehost_images=false to keep original URLs. It does not say when to prefer this over helpcenter_update_article or helpcenter_bulk_create_articles, which is the main missing routing guidance.

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

All HelpCenter.io for agents toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources