Skip to content

Grading with dryRun

Two tools grade assignments: get_submission reads one student's work and grade_submission proposes or saves a grade. grade_submission is a dry run by default: nothing is saved until the call carries dryRun: false. The grade_assignment prompt and the moodle-grading skill tell the agent to wait for the teacher's confirmation before that second call.

Requirements

  • get_submission: scope read and mod/assign:grade. Separate groups and blind marking are respected.
  • grade_submission: scope write, write tools switched on, and mod/assign:grade. The student must be enrolled.

Flow

  1. Find the assignment (get_course_structure, list_activities or a cmid the teacher gave). See who is waiting with get_submissions_status.

  2. Read the work:

    {"cmid": 314, "username": "ada"}

    get_submission returns status, date, attempt, the online text as plain text, files (with the text of txt, md, html and simple PDFs), the current grade and comment, and the rubric or marking guide with criterion and level ids.

  3. Propose a grade with a dry run (the default):

    {"cmid": 314, "username": "ada", "grade": 8.5, "comment": "Clear method; check the units in part 2."}

    The reply has dryRun: true, saved: false and proposed, next to the current submission. Show it to the teacher.

  4. Only after the teacher confirms, send the same proposal with dryRun: false:

    {"cmid": 314, "username": "ada", "grade": 8.5, "comment": "Clear method; check the units in part 2.", "dryRun": false}

Rubrics

When the assignment uses a rubric, send criteria with a criterionId and levelId for every criterion (ids from get_submission), plus an optional remark. The stored grade is the one the rubric calculates.

{"cmid": 314, "userId": 57, "criteria": [{"criterionId": 11, "levelId": 33}, {"criterionId": 12, "levelId": 37, "remark": "Good sources."}]}

Marking guides and scales are returned by get_submission, but grade_submission does not fill them in.

Notifications and groups

  • notify defaults to false. Set it to true only if the teacher wants Moodle to email the student.
  • In a group assignment the grade applies to the whole group.
  • comment left out keeps the current feedback comment.
  • A grade must be between 0 and the assignment maximum.

Every call is recorded as the tool_called event on the assignment. See Event logging.