Skip to main content
Glama

Sergio by Serviche

Create a training module

create_training_module
Idempotent

Creates a DRAFT training module as Training > New module does (owner or admin seats only): title, description, atom_order (handbook article ids in lesson order; omitted = every active staff article, sorted by bucket). Nobody sees it until it is published. When the person names existing training ("add to our new-hire training"), read training_modules and edit that module instead; create one only when none fits. Before adding anything to the handbook, search the sops read entity by the topic (search finds by meaning): when an article already covers it, put the new text into that article (edit_handbook_article with its full content_md, the new lines placed where they belong, or draft_handbook_edit) instead of a new one; create a new article only when none fits, and say which closest article you found and why it did not fit. Audience comes from the person's words: cleaner SOPs, cleaning standards or staff = cleaner; policies, office or VA = va; when the words do not say, ask in one line. Ask which place, in one line naming both, when two places fit the person's words equally well: two articles, or two training modules that both match (two new-hire modules are a tie whatever their status, draft or published); a place the person named outright is never a tie. The proposed change is the confirmation, so never ask "should I add this?" first. Pass the same idempotency_key when retrying; a repeat returns the same module.

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": {
      "title": "<title>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "create_training_module"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleYes
atom_orderNo
descriptionNo
idempotency_keyYesYour id for this operation (8-128 of A-Z a-z 0-9 . _ : -). Reuse it on every retry of the same operation; use a new one for a new operation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations (idempotentHint, destructiveHint=false) it discloses that the module is invisible until published, that owner/admin seats are required, that omitted atom_order defaults to every active staff article sorted by bucket, and that reusing idempotency_key returns the same module on retry. That is substantive behavior the annotations cannot express.

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?

Purpose and scope are front-loaded, but the body drifts into general handbook policy (searching sops by meaning, create_handbook_article vs draft_handbook_edit, audience mapping to cleaner/va) that is only loosely tied to creating a module. It reads as a dense block of prose rather than a structured definition, and a reader has to sift to find the module-specific rules.

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?

Covers auth, draft visibility, atom_order defaults, idempotency behavior and clarification protocol, which is most of what a 4-parameter create tool needs without an output schema. The only real gap is the return shape beyond 'a repeat returns the same module', e.g. what id the created module exposes for follow-up edits.

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

Parameters5/5

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

Schema description coverage is only 25% (only idempotency_key is documented), so the description has to carry the load and it does: atom_order is defined as handbook article ids in lesson order with a documented default, and title/description are implicitly tied to the module's visible fields. Retry semantics for idempotency_key are restated in operational terms.

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

Purpose5/5

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

First sentence gives a specific verb and resource ('Creates a DRAFT training module') and pins the state ('DRAFT', 'Nobody sees it until it is published'), which separates it from edit_training_module and the handbook-article siblings. The parenthetical '(owner or admin seats only)' adds a scope constraint an agent can reason about immediately.

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 routing rules: read training_modules and edit that module when the person names existing training; create only when none fits. It also gives tie-breaking rules (ask which place when two modules match, a named place is never a tie) and says never to pre-ask for confirmation, which is exactly the when/when-not guidance an agent needs.

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