Skip to main content
Glama

Create or update course assessment

upsert_course_assessment
DestructiveIdempotent

Atomically creates or updates the course assessment and learner settings. Requires the course to have certification_mode through_assessment, explicitly requested by the user. Use a lesson quiz for a knowledge check without certification. Generate questions from the relevant chapter or course lesson context and the user goal; avoid unsupported claims, cover the important objectives, and present a concise preview before saving when intent is ambiguous. Choice refs may repeat between questions because Trainn namespaces them.

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": {
      "course_id": "<course_id>",
      "expected_revision": "<expected_revision>",
      "idempotency_key": "<idempotency_key>",
      "assessment": "<assessment>"
    },
    "name": "upsert_course_assessment"
  }
}

Input Schema

NameRequiredDescriptionDefault
course_idYes
assessmentYes
idempotency_keyYes
expected_revisionYes

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds the useful 'atomically' guarantee and the certification-mode gate, which annotations do not convey. However, it never says what an update replaces — whether existing questions or learner attempts are discarded — nor how expected_revision/idempotency_key govern conflict and retry behavior, which matter greatly for a destructive nested upsert.

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?

Front-loads the operation and the precondition, then the alternative, then content guidance, so the most decision-relevant information comes first. Some of the question-authoring advice ('avoid unsupported claims, cover the important objectives') reads more like generation prompting than tool specification and could be tightened.

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?

Combining this with the tool's destructiveHint=true, the missing output schema, and the 0% schema coverage makes the omission of update semantics consequential. The definition covers purpose, gating, alternative, and content expectations well, but not result/concurrency behavior.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must carry parameter meaning; it only explains one thing — that choice refs may repeat across questions because Trainn namespaces them, clarifying client_ref scoping. It says nothing about course_id, expected_revision (a concurrency token), idempotency_key, or the assessment fields such as pass_percentage and attempt_policy, leaving most of a large nested schema unexplained.

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?

States a specific verb and resource ('atomically creates or updates the course assessment and learner settings') plus a scope condition (certification_mode through_assessment). It also explicitly differentiates from the sibling concept 'lesson quiz', so an agent can distinguish it without opening the 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?

Gives an explicit precondition for use (course must have certification_mode through_assessment and be explicitly requested by the user), names the alternative ('use a lesson quiz for a knowledge check without certification'), and adds a decision rule for ambiguity ('present a concise preview before saving when intent is ambiguous').

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