ufsc-moodle-mcp

Criar grupo e matricular participantes em uma única operação composta

create_group_with_members

Idempotent

Creates a Moodle course group and adds specified enrolled participants, validating permissions, enrollment, and capacity while reporting partial failures and final state.

Instructions

Cria um grupo novo na disciplina (com nome escolhido ou único gerado automaticamente, disponível no mod_groupselect) e adiciona os participantes informados de forma idempotente, validando previamente permissões, matrícula e limite máximo de vagas, relatando qualquer falha parcial e confirmando o estado final no Moodle.

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": {
      "userIds": "<userIds>"
    },
    "name": "create_group_with_members"
  }
}

Input Schema

Name	Required	Description
`name`	No	Nome desejado para o grupo (se omitido, gera nome único automaticamente).
`userIds`	Yes	Lista de userIds dos participantes matriculados a adicionar ao grupo.
`courseId`	No	ID da disciplina no Moodle.
`idnumber`	No	Identificador externo opcional (idnumber) do grupo.
`groupingId`	No	ID opcional de agrupamento ao qual associar o grupo.
`namePrefix`	No	Prefixo opcional para geração automática de nome (ex: "Grupo ").
`description`	No	Descrição opcional do grupo.
`activityCmid`	No	Course module ID opcional da atividade mod_groupselect (ex: 1569070).
`enrolmentKey`	No	Chave de inscrição opcional do grupo.
`idempotencyKey`	No	Chave opcional de idempotência para recuperação segura após timeout ou falha parcial.
`autoGenerateName`	No	Se true (padrão quando name é omitido), gera nome único a partir dos grupos existentes.
`allowMultipleGroups`	No	Se false (padrão), impede adicionar aluno já vinculado a outro grupo na mesma atividade.
`prevalidateAllMembers`	No	Se true (padrão), aborta antes de criar o grupo caso algum userId não esteja matriculado na disciplina; se false, cria o grupo, adiciona os válidos e reporta partial_failure para os inválidos.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.2.1Nov 7, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnly=false, idempotent=true, destructive=false; the description goes further by disclosing pre-validation of permissions, enrolment and maximum slots, partial-failure reporting, and confirmation of final Moodle state. All of this is consistent with the annotations rather than contradicting them.

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?

Purpose is front-loaded in a single dense sentence with no filler. The long clause chain (validation, idempotency, partial failures, final state) is slightly hard to parse but every clause carries real information.

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?

With thirteen parameters and no output schema, the description does the important work of explaining the validation/partial-failure model and final-state confirmation. Return shape details are left implicit, which is acceptable because the failure modes are described semantically.

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 every parameter is already documented, and the baseline of 3 applies. The description does add framing about automatic name generation and idempotent participant addition, but it does not explain the interplay of the thirteen parameters beyond what the schema already says.

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

Purpose4/5

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

States a concrete verb+resource pair: creates a new group in the course and adds the given participants, explicitly framing it as a single composite operation. That composite framing implicitly separates it from the create-course-group / add-group-member siblings, though no sibling is named outright.

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?

The composite nature gives clear context for when to reach for this tool rather than two separate calls, and it notes the group name is available in mod_groupselect. It stops short of explicit when-not guidance or naming the sibling tools to use instead.

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