MCP Tools Reference: classroommcp.googleapis.com

Tool: list_course_work_submissions

Lists student submissions for a coursework item. By default returns only studentId, studentName, state, late, and gradePercentage. Set includeStudentWork=true when you need submission attachments (e.g. Google Docs with student work), question answers, or rubric grades; the work of the students in studentIds is always returned.

For students, list_course_work_summaries with includeSubmissionOverview=true already returns their state and grade across all coursework; only call this tool (with includeStudentWork=true) when you need their submitted attachments, question answer, or rubric grades.

To link a teacher to the student work page of an ASSIGNMENT in the Classroom web app, use https://classroom.google.com/c/{course_id}/a/{course_work_id}/submissions/by-status/and-sort-last-name/all. For questions, link to the coursework item instead. Use IDs exactly as returned; never guess or modify them.

The following code sample shows how to use curl to call the list_course_work_submissions MCP tool.

Curl Request 
curl --location 'https://classroommcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_course_work_submissions",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request to retrieve submissions for a course work item.

ListCourseWorkSubmissionsRequest

JSON representation 
{
  "courseId": string,
  "courseWorkId": string,
  "includeStudentWork": boolean,
  "studentIds": [
    string
  ],
  "submissionStates": [
    enum (State)
  ],
  "pageSize": integer,
  "pageToken": string,

  "late": boolean
}
Fields
courseId

string

Required. Identifier of the course.
courseWorkId

string

Required. Identifier of the coursework item.
includeStudentWork

boolean

Optional. Whether to also return each student's work: attachments, answer, and rubricGrades. Otherwise only studentId, state, late, and gradePercentage are returned. Student work is always returned when studentIds is set.
studentIds[]

string

Only retrieve these students' submissions, including their work.
submissionStates[]

enum (State)

Filter by submission states.
pageSize

integer

Maximum number of submissions per page. Defaults to 10; max 50.
pageToken

string

Token for pagination.
late

boolean

Filter by whether the submission was turned in late.

State

States of a submission.

Enums
STATE_UNSPECIFIED Unspecified state.
ASSIGNED Student has been assigned the work but has not turned it in.
MISSING Student has not turned in the work and it is past the due date.
TURNED_IN Student has turned in the work.
RETURNED Teacher has returned the work to the student.
EXCUSED Student is excused from this work.
GRADED Teacher has graded the work.

Output Schema

Response containing submissions.

ListCourseWorkSubmissionsResponse

JSON representation 
{
  "submissions": [
    {
      object (Submission)
    }
  ],
  "nextPageToken": string
}
Fields
submissions[]

object (Submission)

List of submissions.
nextPageToken

string

Token to retrieve the next page of results.

Submission

JSON representation 
{
  "studentId": string,
  "state": enum (State),
  "attachments": [
    {
      object (Attachment)
    }
  ],
  "rubricGrades": [
    {
      object (RubricGrade)
    }
  ],
  "studentName": string,

  "late": boolean

  "gradePercentage": number

  "answer": string
}
Fields
studentId

string

Identifier of the student.
state

enum (State)

Output only. State of the submission.
attachments[]

object (Attachment)

Materials attached to the submission (excluding notebooks). Only populated when student work is included.
rubricGrades[]

object (RubricGrade)

Rubric grades associated with the submission. Only populated when student work is included.
studentName

string

Output only. Name of the student. Omitted if it couldn't be looked up.
late

boolean

Whether the submission was turned in late.
gradePercentage

number

Assigned grade as a percentage of the maximum points. Can exceed 100 with extra credit. Unset if ungraded.
answer

string

Only set for question coursework types. Only populated when student work is included.

Attachment

JSON representation 
{

  "sharedDriveFile": {
    object (SharedDriveFile)
  },
  "youtubeVideo": {
    object (YouTubeVideo)
  },
  "link": {
    object (Link)
  },
  "form": {
    object (Form)
  }
}
Fields
Union field content. The attachment content. content can be only one of the following:
sharedDriveFile

object (SharedDriveFile)

Google Drive file attachment.
youtubeVideo

object (YouTubeVideo)

YouTube video attachment.
link

object (Link)

URL link attachment.
form

object (Form)

Google Forms attachment.

SharedDriveFile

JSON representation 
{
  "file": {
    object (DriveFile)
  },
  "shareMode": enum (ShareMode)
}
Fields
file

object (DriveFile)

Drive file details.
shareMode

enum (ShareMode)

Required. How students get the file: VIEW (read only), EDIT (everyone edits the same file), or COPY (each student gets their own copy).

DriveFile

JSON representation 
{
  "id": string,
  "title": string,
  "url": string
}
Fields
id

string

Required. Identifier of the Drive file.
title

string

Output only. Title of the Drive file.
url

string

Output only. URL of the Drive file.

YouTubeVideo

JSON representation 
{
  "id": string,
  "title": string
}
Fields
id

string

Required. YouTube video ID.
title

string

Output only. Title of the YouTube video.
JSON representation 
{
  "url": string,
  "title": string
}
Fields
url

string

Required. URL of the link.
title

string

Output only. Title of the link.

Form

JSON representation 
{
  "formUrl": string,
  "title": string,
  "responseUrl": string
}
Fields
formUrl

string

Required. URL of the form.
title

string

Output only. Title of the form.
responseUrl

string

Output only. URL of the form response. Only set if responses have been recorded and only when the requesting user is an editor of the form.

RubricGrade

JSON representation 
{
  "criterionId": string,
  "levelId": string,
  "criterionTitle": string,
  "levelTitle": string,

  "points": number
}
Fields
criterionId

string

Identifier of the rubric criterion.
levelId

string

Identifier of the level selected for the criterion.
criterionTitle

string

Title of the rubric criterion. Omitted if the rubric couldn't be read or the criterion wasn't found in the rubric.
levelTitle

string

Title of the level selected for the criterion. Omitted if the level has no title, the rubric couldn't be read, or the level wasn't found.
points

number

Points assigned for the selected level.

State

States of a submission.

Enums
STATE_UNSPECIFIED Unspecified state.
ASSIGNED Student has been assigned the work but has not turned it in.
MISSING Student has not turned in the work and it is past the due date.
TURNED_IN Student has turned in the work.
RETURNED Teacher has returned the work to the student.
EXCUSED Student is excused from this work.
GRADED Teacher has graded the work.

ShareMode

Sharing settings for the Drive file.

Enums
SHARE_MODE_UNSPECIFIED Unspecified sharing mode.
VIEW Students can view the shared file.
EDIT Students can edit the shared file.
COPY Students get a personal copy of the shared file.

Tool Annotations

Tool annotations are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.

Along with the title string, the following boolean hints are defined as follows:

  • readOnlyHint: If true, the tool doesn't modify its environment. Default: false.
  • destructiveHint: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
  • idempotentHint: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
  • openWorldHint: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/classroom.coursework.students
  • https://www.googleapis.com/auth/classroom.coursework.students.readonly
  • https://www.googleapis.com/auth/classroom.coursework.me
  • https://www.googleapis.com/auth/classroom.coursework.me.readonly
  • https://www.googleapis.com/auth/classroom.rosters.readonly