ufsc-moodle-mcp

Preparar plano de avaliação em lote para revisão humana (estritamente somente-leitura)

prepare_grading_batch

Read-onlyIdempotent

Prepares and validates a batch of Moodle grades and feedback comments without writing data, detects conflicts or no-op changes, and generates a hashed plan for human authorization.

Instructions

Prepara, valida e calcula o diff completo de um lote de avaliações (notas e/ou gradingFeedbackComments por groupId ou studentId) SEM realizar nenhuma escrita no Moodle. Distingue alterações solicitadas de alterações efetivas: se notas/feedbacks propostos forem idênticos aos já armazenados, classifica a ação como "preserve", reporta status="prepared_no_changes" e readyToCommit=false. Detecta conflitos (grupos gerais inválidos, ambiguidade, bloqueios, notas fora da faixa ou divergências), gera planId + planHash (SHA-256) e detalha os 4 níveis de garantia exigidos para autorização humana.

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": {
      "assignmentId": "<assignmentId>",
      "items": "<items>"
    },
    "name": "prepare_grading_batch"
  }
}

Input Schema

Name	Required	Description
`items`	Yes	Lista de avaliações propostas por grupo ou por estudante.
`courseId`	No	ID opcional da disciplina.
`assignmentId`	Yes	ID da tarefa (assignmentId) no Moodle.
`allowMemberGradeOverride`	No	Se true, permite aplicar avaliação coletiva a um grupo mesmo que seus integrantes tenham notas prévias divergentes entre si (padrão: false, gerando conflito explícito).
`proposedPublicationState`	No	Estado pretendido de publicação ("inmarking", "readyforreview", "inreview", "readyforrelease" ou "released") para validação prévia contra markingworkflow da tarefa.
`proposedNotificationPolicy`	No	Política pretendida de notificação aos estudantes ("suppress", "moodle_default" ou "notify_students").

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.2.1Nov 7, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description reinforces this with an explicit no-write guarantee plus genuinely new behavioral detail: preserve-vs-change classification, conflict categories (invalid general groups, ambiguity, blocks, out-of-range grades), and the generated planId + SHA-256 planHash. It stops short of describing the returned structure or what the "4 níveis de garantia" actually consist of, which is the one piece of behavior an agent would still need.

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?

It is one dense paragraph, but it is front-loaded with the core action and the no-write guarantee, then layers classification, conflict detection, and outputs in a logical order with no filler sentences. The closing clause about "os 4 níveis de garantia exigidos para autorização humana" is the weakest part — it alludes to content it never enumerates.

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 a 6-parameter tool with nested items, no output schema, and mutation-adjacent semantics, the description covers the critical points: nothing is written, a plan/hash is produced, conflicts are surfaced, and a no-change case is explicitly handled. Gaps remain around the exact return payload and the unnamed four guarantee levels, but an agent could call this correctly and interpret the result.

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 the schema already explains every parameter, including the omit-to-preserve semantics for grade and gradingFeedbackComment. The description adds only high-level framing (grades/feedback addressed by groupId or studentId, identical values become "preserve"), which is helpful context but not parameter-level detail beyond the schema. 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?

The description states a specific compound verb set ("prepara, valida e calcula o diff") on a concrete resource ("lote de avaliações") and immediately bounds scope with "SEM realizar nenhuma escrita no Moodle", which separates it from the write-side sibling commit_grading_batch. It also names the two addressing modes (por groupId ou studentId), so an agent knows exactly what class of operation this is before 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?

Usage context is clear: this is the pre-commit preparation step that produces planId/planHash for human authorization, and it explains that a no-op input yields status="prepared_no_changes" and readyToCommit=false. What is missing is an explicit pointer to the alternatives — commit_grading_batch and verify_grading_batch are never named, so the agent must infer the workflow ordering from the read-only framing.

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