Skip to main content
Glama

Create or edit Library article

upsert_library_article
DestructiveIdempotent

Creates a standalone draft article in Trainn Library, or edits an existing standalone article. Write a complete learner-facing article directly from the request; do not ask a generic topic, length, or formatting questionnaire unless a material fact is missing. Use semantic rich HTML (h1–h4, paragraphs, bold, italic, underline, strike, lists, blockquotes, links, tables, code, and verified HTTPS images when available); Trainn stores it as a structured Tiptap document. Never invent image or video URLs. Optional seo_description is the learner-facing summary, up to 500 characters; omit it on edit to keep the current summary, or pass an empty string to clear it. For richer teaching, position an inspected Library video, inspected Library guide, or verified YouTube video in body_html with , then define that name in embeds. Library embeds require the fresh selection_token from inspect_library_content. Use embeds only when the media materially helps the learner; never invent IDs or URLs. folder_id places a new article, or moves an existing one; omit it to use the Library root on create or to leave an existing article where it is. Creating does not publish. For edits, first inspect the current item and provide article_id plus expected_revision. Call publish_library_content only when the user explicitly asks to publish or add it to Library.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "idempotency_key": "<idempotency_key>",
      "title": "<title>",
      "body_html": "<body_html>"
    },
    "name": "upsert_library_article"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleYes
embedsNoOptional rich embeds. Each ref must appear exactly once in body_html as <trainn-embed data-ref="ref"></trainn-embed>. For library_video or library_guide, provide content_id and selection_token from inspect_library_content. For youtube, provide an HTTPS YouTube watch, short, or embed URL.
body_htmlYes
folder_idNoLibrary folder. On create, omit to use the Library root. On edit, omit to leave the article where it is.
article_idNo
idempotency_keyYes
seo_descriptionNoLearner-facing summary shown with the article. Omit on edit to keep the current summary. Pass an empty string to clear it.
expected_revisionNo

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnly=false, but the description adds real substance: creating does not publish, embeds require a fresh selection_token from inspect_library_content, revision conflicts are guarded by expected_revision, and empty-string seo_description clears the summary. It stops short of saying that an edit replaces the entire body_html (the main destructive consequence) or how idempotency_key behaves.

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

Conciseness4/5

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

Dense and front-loaded: creation/edit scope first, then formatting, then embeds, then placement, then publishing. Minor waste from repeated 'never invent ... URLs' warnings (image/video and IDs/URLs) and a somewhat long detour into HTML tag enumeration.

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

Completeness4/5

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

For an 8-parameter mutation tool with no output schema, the description covers the risky paths well (unpublished drafts, embed token freshness, revision guard, folder placement). It is incomplete in two respects: no statement of what a successful call returns (article id, new revision), and no explanation of the required idempotency_key.

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?

With schema coverage at only 38%, the description carries meaningful weight: it explains seo_description length/clear-on-empty semantics, folder_id create-vs-edit behavior, expected_revision for concurrency, and body_html's expected rich-HTML surface stored as Tiptap. Gaps remain for idempotency_key (never explained despite being required) and the embed 'type'/'url' pairing beyond the schema's own text.

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 with scope: 'Creates a standalone draft article in Trainn Library, or edits an existing standalone article.' 'Standalone' usefully narrows the resource, but the description never distinguishes this upsert from the sibling update_library_content, leaving some ambiguity about which write path to pick.

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

Usage Guidelines5/5

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

Explicit when-to-use and when-not guidance: write directly without asking a generic questionnaire, use embeds only when media materially helps, omit folder_id to use root on create or leave placement untouched on edit, and 'Call publish_library_content only when the user explicitly asks to publish.' It also gives the edit prerequisite (inspect first, supply article_id plus expected_revision).

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources