tool_smart_read_submission
Generate a prioritized reading plan for student submissions by organizing pages into tiers: crop regions first, then full pages, and adjacent pages if needed, with confidence scores and recommended actions.
Instructions
Get a smart, tiered reading plan for a student's submission.
Returns page URLs in priority order:
- Tier 1: Crop region only (read FIRST)
- Tier 2: Full page (if answer overflows crop)
- Tier 3: Adjacent pages (if still incomplete)
Also returns confidence score and recommended action.
Args:
course_id: The Gradescope course ID.
assignment_id: The assignment ID.
question_id: The question ID.
submission_id: The question submission ID.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | Yes | ||
| assignment_id | Yes | ||
| question_id | Yes | ||
| submission_id | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The core implementation of the smart_read_submission tool logic.
def smart_read_submission( course_id: str, assignment_id: str, question_id: str, submission_id: str, ) -> str: """Get a smart, tiered reading plan for a student's submission. Returns page image URLs in priority order: 1. **Tier 1 (Crop Only):** The crop region URLs for the question's designated area. Agent should read ONLY this first. If the answer is fully contained, grade it. 2. **Tier 2 (Full Page):** If handwriting exits the crop boundary or reasoning appears truncated, read the full page(s) containing the crop. 3. **Tier 3 (Adjacent Pages):** If the answer still appears incomplete, read the previous and next pages. Also returns the confidence score to decide whether to auto-grade or skip. Args: course_id: The Gradescope course ID. assignment_id: The assignment ID. question_id: The question ID. submission_id: The question submission ID. """ if not course_id or not assignment_id or not question_id or not submission_id: return "Error: all four IDs are required." try: questions = _fetch_assignment_questions(course_id, assignment_id) ctx = _get_grading_context(course_id, question_id, submission_id) prompt_text, explanation = _extract_outline_prompt_and_reference( course_id, assignment_id, question_id, ) except AuthError as e: return f"Authentication error: {e}" except (ValueError, Exception) as e: - src/gradescope_mcp/server.py:704-728 (registration)Tool registration for tool_smart_read_submission, which wraps the smart_read_submission helper function.
@mcp.tool() def tool_smart_read_submission( course_id: str, assignment_id: str, question_id: str, submission_id: str, ) -> str: """Get a smart, tiered reading plan for a student's submission. Returns page URLs in priority order: - Tier 1: Crop region only (read FIRST) - Tier 2: Full page (if answer overflows crop) - Tier 3: Adjacent pages (if still incomplete) Also returns confidence score and recommended action. Args: course_id: The Gradescope course ID. assignment_id: The assignment ID. question_id: The question ID. submission_id: The question submission ID. """ return smart_read_submission( course_id, assignment_id, question_id, submission_id )