Skip to main content
Glama

Sergio by Serviche

Edit or publish a training module

edit_training_module
Idempotent

Edits a training module as its page does (owner or admin seats only): title, description, atom_order, context_position (before or after), status draft or published. Publishing puts it on the team's own training page (nothing is sent) and is refused until every atom has quiz questions (generate_training_questions). To add something to training ("add that to new-hire training"): read training_modules for the module the person means (by title and description), find or create the handbook article that holds the text (search sops first, as the handbook tools say), then send atom_order as the module's current order with that article id placed where it belongs; an article already in atom_order needs only its article edited. A module that gains an atom needs questions for it (generate_training_questions) before it can be published again. 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.

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": {
      "module_id": "<module_id>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "edit_training_module"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleNo
statusNo
module_idYes
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.
context_positionNo

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, the description discloses the owner/admin permission gate, a hard precondition (publishing is refused until every atom has quiz questions), and the blast radius of publishing ("puts it on the team's own training page (nothing is sent)"). Those are exactly the mutation facts an agent needs and none of them are recoverable from readOnlyHint=false or destructiveHint=false.

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?

It is front-loaded correctly, with the direct edit semantics first and the add-to-training workflow after. But the middle is a dense run-on paragraph packing handbook search, article selection, audience inference, tie-breaking and confirmation policy into long multi-clause sentences that are hard to scan and partly duplicate each other (handbook dedup is stated twice).

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 mutating tool with no output schema and 14% schema coverage, the description covers purpose, permissions, preconditions, side effects, retry safety and the full multi-step workflow that leads into it. An agent has everything required to call it correctly and to know when not to.

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 description coverage is only 14%, so the description carries the load and mostly does: it explains atom_order operationally (the module's current order with the article id placed where it belongs), context_position as before/after, status as draft or published, and repeats idempotency_key retry semantics. module_id and the 300-item atom_order cap are left to the schema, keeping it short of a 5.

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?

The first sentence states a specific verb and resource ("edits a training module") and enumerates the exact mutable fields: title, description, atom_order, context_position, status. It also names the seat requirement, which distinguishes it from create_training_module and archive_training_module without opening any schema.

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?

It gives explicit routing rules: use generate_training_questions before publishing, use search sops to find existing articles and edit_handbook_article or draft_handbook_edit instead of creating a duplicate, and ask a one-line question when two places tie. It also excludes a behavior ("never ask 'should I add this?' first"), which is rare and useful.

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