Skip to main content
Glama

Generate Quiz or Mock Exam

request-creation

Ask Studocu to generate a quiz or mock exam from 1 to 10 project sources. Can take about 3 minutes. If status is creating or outcome_unknown, check get-project-state before calling again.

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": {
      "project_id": "<project_id>",
      "type": "<type>",
      "artifact_ids": "<artifact_ids>"
    },
    "name": "request-creation"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeYesWhat to generate: quiz or mockExam.
project_idYesUUID of the project that owns the project sources. Example: 11111111-1111-4111-8111-111111111111. From create-project or get-context.
instructionNoOptional hint, 1-6000 characters. Example: "focus on chapter 3". Omit for a general quiz or mock exam.
artifact_idsYes1 to 10 different project source ids to generate from. Each id looks like studocu://project/{project_id}/source/{uuid} and must belong to project_id. Get them from add-document-sources or get-project-state. Do not pass creation ids.
idempotency_keyNoOptional retry key, 1-256 characters. Send the same key when you retry the same request. A different request body with a used key is rejected. Omit to let Studocu derive a key from the request; identical retries still count as the same request.

Output Schema

NameRequiredDescriptionDefault
urlNoStudocu web link for the user: the creation when status is created, otherwise its project. Share it with the user.
typeYes
statusYescreated: saved, with artifact_id and external_id. creating: generation finished but the new creation is not linked yet; match external_id on get-project-state. outcome_unknown: the call timed out or a duplicate is still running; check get-project-state and do not send a new retry key. Failures come back as errors, not as a status.
artifact_idNoAgent OS artifact ID of the new creation. Present when status is created.
external_idNoQuiz id or mock-exam id. Present when status is created or creating. Match it on get-project-state. Omitted when the call times out.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedOutput schema / properties / url
      Added value: +{
      +  "description": "Studocu web link for the user: the creation when status is created, otherwise its project. Share it with the user.",
      +  "type": "string"
      +}
  2. Changed7 schema fields changed
    • changedInput schema / properties / artifact_ids / description
      Previous value: -"One to ten unique source artifact IDs (studocu://project/{project_id}/source/{uuid}) to generate from."New value: +"1 to 10 different project source ids to generate from. Each id looks like studocu://project/{project_id}/source/{uuid} and must belong to project_id. Get them from add-document-sources or get-project-state. Do not pass creation ids."
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Optional retry key. Agent OS always sends Idempotency-Key to Alpha (this value, or a fingerprint of project/type/sources/instruction). Reuse with a different body is rejected."New value: +"Optional retry key, 1-256 characters. Send the same key when you retry the same request. A different request body with a used key is rejected. Omit to let Studocu derive a key from the request; identical retries still count as the same request."
    • changedInput schema / properties / instruction / description
      Previous value: -"Optional free-text hint for the generating agent (e.g. \"focus on chapter 3\")."New value: +"Optional hint, 1-6000 characters. Example: \"focus on chapter 3\". Omit for a general quiz or mock exam."
    • changedInput schema / properties / project_id / description
      Previous value: -"UUID of the Studocu project that will own the new creation."New value: +"UUID of the project that owns the project sources. Example: 11111111-1111-4111-8111-111111111111. From create-project or get-context."
    • changedInput schema / properties / type / description
      Previous value: -"The kind of creation to generate: quiz or mockExam."New value: +"What to generate: quiz or mockExam."
    • changedOutput schema / properties / external_id / description
      Previous value: -"Kind-specific downstream id (quizId or mockExamId). Present on created and creating; match the same field on get-project-state creation rows. Omitted on timeout."New value: +"Quiz id or mock-exam id. Present when status is created or creating. Match it on get-project-state. Omitted when the call times out."
    • changedOutput schema / properties / status / description
      Previous value: -"created: persisted and linked (artifact_id and external_id). creating: generation finished but Alpha identity is not yet visible (external_id matches get-project-state creation rows). outcome_unknown: client timeout or an in-flight duplicate (check get-project-state; do not mint a new key). Terminal failures use MCP isError, not a status value."New value: +"created: saved, with artifact_id and external_id. creating: generation finished but the new creation is not linked yet; match external_id on get-project-state. outcome_unknown: the call timed out or a duplicate is still running; check get-project-state and do not send a new retry key. Failures come back as errors, not as a status."
  3. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the description's real value is the async behavior it adds: about 3 minutes of latency and the existence of creating/outcome_unknown states that block a re-call. That is useful context beyond the annotations and does not contradict them.

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

Conciseness5/5

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

Three short sentences, front-loaded with the action and scope, then duration, then the retry guard. Nothing is padded and each sentence carries a distinct instruction.

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?

An output schema exists so return values need no explanation, and the description covers the one thing an agent would otherwise get wrong: that this is a slow asynchronous generation requiring a state check before re-invocation. A little more on failure/partial outcomes would make it complete.

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 100%, so all five parameters including the quiz/mockExam enum are already documented in the schema. The description only restates the 1-to-10 source count and adds no new meaning about project_id, instruction, or idempotency_key, so baseline 3 applies.

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 ('generate a quiz or mock exam') plus an explicit scope ('from 1 to 10 project sources'), which cleanly separates it from siblings like get-project-state or read-artifact. An agent knows exactly what this call produces 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 Guidelines4/5

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

Gives one concrete when-not rule and names the alternative: if status is creating or outcome_unknown, call get-project-state instead of retrying. It does not say when to pick quiz versus mockExam or how this relates to write-artifact, so guidance is clear but not exhaustive.

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