tool_get_assignment_submissions
Retrieve all student submissions for a specific assignment in Gradescope, providing submission IDs and file counts for instructor or TA review.
Instructions
Get all submissions for an assignment (instructor/TA only).
Returns a list of submission IDs and file counts.
Note: May be slow for large classes as it fetches each submission individually.
Args:
course_id: The Gradescope course ID.
assignment_id: The assignment ID.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | Yes | ||
| assignment_id | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The core implementation of get_assignment_submissions that fetches submission data from the Gradescope API.
def get_assignment_submissions(course_id: str, assignment_id: str) -> str: """Get all submissions for an assignment (instructor/TA only). Works for all assignment types: scanned PDF, online, and code assignments. Returns submission IDs, graded status, and grading progress. Note: The returned IDs are **Global Submission IDs** (the whole assignment submission). For grading a specific question, you may need the per-question submission ID from `get_submission_grading_context`. Args: course_id: The Gradescope course ID. assignment_id: The assignment ID. """ if not course_id or not assignment_id: return "Error: both course_id and assignment_id are required." try: conn = get_connection() # Primary: submissions.json (works for scanned PDF/image assignments) resp = conn.session.get( f"{conn.gradescope_base_url}/courses/{course_id}" f"/assignments/{assignment_id}/submissions.json", headers={ "Accept": "application/json", "X-Requested-With": "XMLHttpRequest", }, ) if resp.status_code == 200: return _format_submissions_json(resp.json(), assignment_id, course_id) # Fallback: scrape review_grades HTML table (works for online assignments) return _get_submissions_from_review_grades(conn, course_id, assignment_id) except AuthError as e: return f"Authentication error: {e}" except Exception as e: return f"Error fetching submissions: {e}" def _format_submissions_json(data: dict, assignment_id: str, course_id: str) -> str: """Format submission data from the submissions.json endpoint.""" detailed = data.get("detailed_submissions", {}) basic = data.get("submissions", {}) if not detailed and not basic: return f"No submissions found for assignment `{assignment_id}` in course `{course_id}`." subs = detailed or basic total = len(subs) - src/gradescope_mcp/server.py:242-255 (registration)The registration of the tool_get_assignment_submissions function as an MCP tool using the @mcp.tool decorator.
@mcp.tool() def tool_get_assignment_submissions( course_id: str, assignment_id: str ) -> str: """Get all submissions for an assignment (instructor/TA only). Returns a list of submission IDs and file counts. Note: May be slow for large classes as it fetches each submission individually. Args: course_id: The Gradescope course ID. assignment_id: The assignment ID. """ return get_assignment_submissions(course_id, assignment_id)