## Tool: `list_courses`

> [!WARNING]
> **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview.md.txt), which grants early access to certain features.

Lists the user's courses with their details (section, room, subject, grade levels, description, learning goals, state, and the user's role). Use this as the primary entry point to discover courses and retrieve their IDs. Courses often share a title, so use section to tell them apart. Returns only ACTIVE courses unless courseState is set (e.g. ARCHIVED).

To link the user to a course in the Classroom web app, use <https://classroom.google.com/c/{course_id>} (stream) or <https://classroom.google.com/w/{course_id}/t/all> (Classwork page). Use IDs exactly as returned; never guess or modify them.

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

| Curl Request |
|---|
| ```bash 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_courses", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request to list courses.

### ListCoursesRequest

| JSON representation |
|---|
| ``` { "courseState": enum (`State`), "createdDateRange": { object (`DateRange`) }, "timeZone": string, "titleContains": string, "pageSize": integer, "pageToken": string } ``` |

| Fields ||
|---|---|
| `courseState` | ``enum (`State`)`` Optional. Filter by course state. Defaults to `ACTIVE`. |
| `createdDateRange` | ``object (`DateRange`)`` Optional. Filter by range of creation dates. |
| `timeZone` | `string` Required. The user's IANA timezone (e.g. `"America/Los_Angeles"`). Dates in this request are interpreted in it and dates in the response are formatted in it, matching what the user sees in Classroom. |
| `titleContains` | `string` Optional. Filter title by case-insensitive substring. |
| `pageSize` | `integer` Optional. Controls page size. Defaults to 10; max 50. |
| `pageToken` | `string` Optional. Token for pagination. |

### DateRange

| JSON representation |
|---|
| ``` { "startDate": string, "endDate": string } ``` |

| Fields ||
|---|---|
| `startDate` | `string` Inclusive start of the range (format: YYYY-MM-DD). |
| `endDate` | `string` Inclusive end of the range (format: YYYY-MM-DD). |

### State

States of a course.

| Enums ||
|---|---|
| `STATE_UNSPECIFIED` | Unspecified state. |
| `ACTIVE` | Active state. |
| `ARCHIVED` | Archived state. |
| `PROVISIONED` | Provisioned state. |

## Output Schema

Response to list courses.

### ListCoursesResponse

| JSON representation |
|---|
| ``` { "courses": [ { object (`Course`) } ], "nextPageToken": string } ``` |

| Fields ||
|---|---|
| `courses[]` | ``object (`Course`)`` The list of courses. |
| `nextPageToken` | `string` The next page token. |

### Course

| JSON representation |
|---|
| ``` { "id": string, "title": string, "role": enum (`Role`), "creationDate": string, "state": enum (`State`), "section": string, "room": string, "subject": string, "gradeLevels": string, "description": string, "learningGoals": [ { object (`LearningGoal`) } ] } ``` |

| Fields ||
|---|---|
| `id` | `string` Identifier. Identifier for this course. |
| `title` | `string` Title of the course. |
| `role` | ``enum (`Role`)`` Role of the user in this course. |
| `creationDate` | `string` Creation date of the course (format: YYYY-MM-DD). Empty if the creation date isn't known. |
| `state` | ``enum (`State`)`` Output only. State of the course. |
| `section` | `string` Optional. Section of the course. |
| `room` | `string` Optional. Room of the course. |
| `subject` | `string` Optional. Subject of the course. |
| `gradeLevels` | `string` Optional. Grade levels of the course. |
| `description` | `string` Optional. Description of the course. |
| `learningGoals[]` | ``object (`LearningGoal`)`` Output only. Learning goals attached to this course. |

### LearningGoal

| JSON representation |
|---|
| ``` { "id": string, "type": enum (`Type`), "standardCode": string, "title": string, "documentTitle": string } ``` |

| Fields ||
|---|---|
| `id` | `string` Output only. ID of the learning goal. To attach a standard, use an `id` from search_course_standards (not `standardCode`). |
| `type` | ``enum (`Type`)`` Output only. The type of learning goal. |
| `standardCode` | `string` Output only. Standard code (e.g. "NY-2.NBT.4"). Only populated for standards. |
| `title` | `string` Output only. Statement description for standards, or human-readable title for skills. |
| `documentTitle` | `string` Output only. Curriculum document name. Only populated for standards. |

### Role

Roles of a user in a course.

| Enums ||
|---|---|
| `ROLE_UNSPECIFIED` | Unspecified role. |
| `TEACHER` | Teacher role. |
| `COTEACHER` | Co-teacher role. |
| `STUDENT` | Student role. |
| `INVITED_OR_INACTIVE` | Invited or inactive role. |

### State

States of a course.

| Enums ||
|---|---|
| `STATE_UNSPECIFIED` | Unspecified state. |
| `ACTIVE` | Active state. |
| `ARCHIVED` | Archived state. |
| `PROVISIONED` | Provisioned state. |

### Type

The type of learning goal.

| Enums ||
|---|---|
| `TYPE_UNSPECIFIED` | Unspecified learning goal type. |
| `STANDARD` | A learning standard from an academic curriculum. |
| `SKILL` | A skill representing an educational concept or competency. Only a teacher can add or remove skills, in Classroom. |

### Tool Annotations


[Tool annotations](https://modelcontextprotocol.io/specification/latest/schema#toolannotations) 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.courses.readonly`
- `https://www.googleapis.com/auth/classroom.rosters.readonly`