What can you do with this server?

The Gradescope MCP Server enables AI agents and MCP clients to interact with Gradescope for course management, grading, and AI-assisted workflows through 34 tools, 3 resources, and 7 prompts. Course & Assignment Management * List all courses (grouped by role), assignments (with dates/status), and detailed assignment info * Rename assignments and modify release, due, and late-due dates Roster, Extensions & Submissions * View full course roster (students, TAs, instructors) with name, email, SID, and submission count * View, add, or update student extensions * Upload files as submissions, list all submissions, and view a specific student's submission Grading (Read) * Get the hierarchical question/rubric outline (IDs, weights, prompt text) * Export per-question scores with statistics and breakdowns * View grading progress dashboard (completion % per question) * Get full grading context for a submission (rubric, evaluations, score, comments, navigation) * Inspect rubric items without needing a submission ID; list submissions filterable by grade state * Navigate to the next ungraded question submission Grading (Write) * Apply grades (rubric items, point adjustments, comments) * Create, update, and delete rubric items (with cascade warnings for high-impact changes) AI-Assisted Workflows * Prepare and cache grading artifacts (prompt, rubric, reference notes, page URLs) to /tmp/gradescope-mcp * Assess submission readiness for auto-grading with a confidence score (below 0.6 rejected, 0.6–0.8 warns, above 0.8 proceeds) * Cache crop and neighboring pages for scanned/handwritten exams * Prepare a complete answer key for an entire assignment * Generate a smart tiered reading plan (crop → full page → adjacent pages) Batch Grading via Answer Groups * List AI-clustered answer groups, inspect members and crops, and batch-grade an entire group at once Regrades & Statistics * List and inspect regrade requests (pending and completed) with student messages and grader responses * Access assignment-level and per-question statistics (mean, median, min/max, std dev) Safety * All write operations are preview-first, requiring explicit confirm_write=True before any mutation is executed

How do I use Gradescope MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Gradescope MCP Server show me any pending regrade requests for the midterm" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Gradescope MCP Server

by Yuanpeng-Li

Overview Schema Source Related Servers Discussions Admin

Python

Remote

The Gradescope MCP Server enables AI agents and MCP clients to interact with Gradescope for course management, grading, and AI-assisted workflows through 34 tools, 3 resources, and 7 prompts.

Course & Assignment Management

List all courses (grouped by role), assignments (with dates/status), and detailed assignment info
Rename assignments and modify release, due, and late-due dates

Roster, Extensions & Submissions

View full course roster (students, TAs, instructors) with name, email, SID, and submission count
View, add, or update student extensions
Upload files as submissions, list all submissions, and view a specific student's submission

Grading (Read)

Get the hierarchical question/rubric outline (IDs, weights, prompt text)
Export per-question scores with statistics and breakdowns
View grading progress dashboard (completion % per question)
Get full grading context for a submission (rubric, evaluations, score, comments, navigation)
Inspect rubric items without needing a submission ID; list submissions filterable by grade state
Navigate to the next ungraded question submission

Grading (Write)

Apply grades (rubric items, point adjustments, comments)
Create, update, and delete rubric items (with cascade warnings for high-impact changes)

AI-Assisted Workflows

Prepare and cache grading artifacts (prompt, rubric, reference notes, page URLs) to /tmp/gradescope-mcp
Assess submission readiness for auto-grading with a confidence score (below 0.6 rejected, 0.6–0.8 warns, above 0.8 proceeds)
Cache crop and neighboring pages for scanned/handwritten exams
Prepare a complete answer key for an entire assignment
Generate a smart tiered reading plan (crop → full page → adjacent pages)

Batch Grading via Answer Groups

List AI-clustered answer groups, inspect members and crops, and batch-grade an entire group at once

Regrades & Statistics

List and inspect regrade requests (pending and completed) with student messages and grader responses
Access assignment-level and per-question statistics (mean, median, min/max, std dev)

Safety

All write operations are preview-first, requiring explicit confirm_write=True before any mutation is executed

Gradescope MCP Server

An MCP (Model Context Protocol) server for Gradescope that exposes course management, grading, regrade review, statistics, and AI-assisted grading workflows to MCP clients.

The server is designed for instructors and TAs who want to use AI agents with real Gradescope data while keeping every write behind a preview and an explicit confirmation step.

This repository also includes a reusable skill at skills/gradescope-assisted-grading/SKILL.md for human-approved grading workflows.

Current Status

39 MCP tools (24 read-only, 11 that write to Gradescope, 4 that only write to the private local cache)
3 MCP resources (1 static resource, 2 URI templates)
7 MCP prompts
Python 3.10+
MCP Python SDK v2 (mcp>=2.2,<3, MCPServer) and gradescopeapi>=1.8.1
Package manager: uv
Offline test suite: uv run pytest -q (the current count is recorded in DEVLOG.md)

Related MCP server: Moodle MCP Server

What The Project Provides

Read-oriented workflows

Course discovery and assignment listing
Assignment outline parsing for online and scanned-PDF assignments
Roster inspection with a custom HTML parser
Submission listing for multiple assignment types
Grading progress, rubric context, answer groups, regrades, and statistics
Workflow helpers that write grading artifacts, answer-key snapshots and page images to a private per-user cache (see Local cache; the tools print the real path)

Write-oriented workflows

Uploading submissions
Setting student extensions
Modifying assignment dates
Renaming assignments
Changing a programming assignment's autograder Docker image
Applying grades, one at a time or in batches
Creating, updating, and deleting rubric items
Batch grading answer groups

Every tool that writes to Gradescope returns a preview unless it is called with confirm_write=True. See Write safety.

Tool Inventory

The Kind column matches the tool annotations clients see: read-only (readOnlyHint), write (changes Gradescope data; destructiveHint, has confirm_write), or local cache (reads Gradescope, writes files only to the private local cache).

Courses And Assignments

Tool	Kind	Description
`tool_list_courses`	read-only	List all courses grouped by role (instructor vs student)
`tool_get_assignments`	read-only	List a course's assignments with dates; status and grade for student accounts (N/A for staff)
`tool_get_assignment_details`	read-only	One assignment's name and dates (status and grade for student accounts)
`tool_upload_submission`	write	Upload local files as a new submission from the logged-in account (path restrictions and success check below)

Instructor / TA Management

Tool	Kind	Description
`tool_get_course_roster`	read-only	Roster grouped by role: name, email, SID, user ID, submission count, sections
`tool_get_extensions`	read-only	Extensions for one assignment: dates as course-local time = UTC instant, plus other settings (e.g. time limit)
`tool_set_extension`	write	Add or update one student's extension; other current settings are re-sent and kept; `timezone` for dates without an offset
`tool_modify_assignment_dates`	write	Change release / due / late-due dates; omitted dates are kept
`tool_rename_assignment`	write	Rename an assignment
`tool_update_autograder_image`	write	Change a programming assignment's autograder Docker Hub image
`tool_get_assignment_submissions`	read-only	Global Submission IDs with graded status, progress and late flag
`tool_get_student_submission`	read-only	One student's typed answers (untrusted blocks), file and page links, per-question and total scores
`tool_get_assignment_graders`	read-only	Staff who last graded a question's submissions, with counts (not the assigned graders)

Grading Read

Tool	Kind	Description
`tool_get_assignment_outline`	read-only	Question hierarchy (nested subparts), IDs, types, weights, prompt text; no rubric items
`tool_export_assignment_scores`	read-only	Score export summary; `output_format="json"` returns every student with per-question scores
`tool_get_grading_progress`	read-only	Per-question graded counts, numbered as in the outline
`tool_get_submission_grading_context`	read-only	Rubric (IDs, applied state), score, typed answer, crop pages ±1; `output_format="json"` available
`tool_get_question_rubric`	read-only	Rubric items and scoring type without a submission ID
`tool_list_question_submissions`	read-only	Question Submission IDs; `filter` = `all` / `ungraded` / `graded` (`graded: null` rows, state unknown, appear only under `all`)
`tool_get_student_submission_map`	read-only	Per-student map of question ID to Question Submission ID, keyed by email
`tool_get_student_assignment_link`	read-only	Per-student whole-assignment submission URL, by name or `student_email`
`tool_get_next_ungraded`	read-only	Grading context of the next ungraded submission of the same question

Grading Write

Tool	Kind	Description
`tool_apply_grade`	write	Set one submission's rubric items, point adjustment and comment; an already graded submission needs `overwrite_graded`; reads the score back
`tool_apply_grade_batch`	write	Grade up to 50 submissions of one question in one call; typed rows, a graded row skipped unless that row has `overwrite: true`, per-row read-back
`tool_create_rubric_item`	write	Create a rubric item (positive weight; ADD/DEDUCT shown in the preview)
`tool_update_rubric_item`	write	Update an existing rubric item's description or weight
`tool_delete_rubric_item`	write	Delete a rubric item (removes it from every submission)

AI-Assisted / Workflow Helpers

Tool	Kind	Description
`tool_prepare_grading_artifact`	local cache	Write a question's grading artifact (prompt, scoring type, signed rubric, reference answer or rubric summary, crops, sample pages) and print its path
`tool_assess_submission_readiness`	read-only	Report pre-read context (prompt, reference, rubric, crop, located student work); not grading confidence
`tool_cache_relevant_pages`	local cache	Download a submission's page images (all pages by default; `include_all_pages=False` for crop pages and neighbours) and print the directory
`tool_prepare_answer_key`	local cache	Write an assignment-wide grading basis (prompts, instructor reference answers) and print its path
`tool_export_lms_gradebook`	local cache	Write the assignment's scores as a Canvas or Brightspace gradebook import CSV (fully graded scores only by default) and print its path
`tool_smart_read_submission`	read-only	Crop-first reading plan: crop page, adjacent pages, other pages; typed answers for online questions

Answer Groups

Tool	Kind	Description
`tool_get_answer_groups`	read-only	AI-clustered answer groups with sizes, graded counts and inferred members
`tool_get_answer_group_detail`	read-only	One group's members, crops and graded counts (confirmed and inferred)
`tool_grade_answer_group`	write	Grade every member of one group; `overwrite_graded` + `expected_graded_ids` and `expected_member_count` guards

Regrades

Tool	Kind	Description
`tool_get_regrade_requests`	read-only	Regrade requests with status ✅ completed / ⏳ pending / ❓ unknown
`tool_get_regrade_detail`	read-only	Current score, adjustment, comment, rubric, pages, staff response and the student's message

Statistics

Tool	Kind	Description
`tool_get_assignment_statistics`	read-only	Assignment summary and per-question averages; flags low-scoring graded questions

Resources

URI	Description
`gradescope://courses`	Current course list
`gradescope://courses/{course_id}/assignments`	Assignment list for a course
`gradescope://courses/{course_id}/roster`	Roster for a course

course_id in a resource URI must be ASCII digits (leading zeros are dropped, as for tool IDs); anything else is a JSON-RPC error (-32602, "Invalid resource URI ..."). A resource whose read fails (for example missing credentials) returns a JSON-RPC error carrying the message instead of content.

Prompts

Prompt	Description
`summarize_course_progress`	Summarize assignment status for a student account, or submission and grading progress for staff
`manage_extensions_workflow`	View extensions, then preview and (after approval) set new ones
`check_submission_stats`	Submission, missing, late and graded counts plus dates for one assignment
`generate_rubric_from_outline`	Propose a rubric per question; nothing is created without previews and approval
`grade_submission_with_rubric`	Grade one student's questions; grades are written only after previews and approval
`review_regrade_requests`	Review open (⏳) and unknown-status (❓) regrade requests; changes only after previews and approval
`auto_grade_question`	Assisted grading for one question: read, propose, preview a batch, get approval, write, verify

Despite its name, auto_grade_question does not grade on its own: it tells the agent to preview each batch (at most 50 rows) with tool_apply_grade_batch(confirm_write=False) and to write only the rows the user explicitly approves. An already graded row is written only if the user approves overwriting that row's grade: the row gets "overwrite": true and the batch is previewed again. review_regrade_requests likewise previews each approved change with tool_apply_grade(overwrite_graded=True, confirm_write=False) (a regraded submission is already graded) and repeats that call with confirm_write=True only after the user approves the preview.

How The Tools Behave

IDs

Every Gradescope ID parameter (course_id, assignment_id, question_id, submission_id, group_id, rubric_item_id, user_id, rubric_item_ids and expected_graded_ids elements, and batch-row IDs) is a string of ASCII digits (^[0-9]+$ in the input schema).
JSON numbers are accepted and converted; surrounding whitespace and backticks are stripped, and leading zeros are dropped ("031" is the same ID as "31", "000" is "0"). Anything else ("../1", "-1", 1.5, true, non-ASCII digits such as "１２３") is rejected before the tool runs.
An optional ID that is blank or null means "not given".

Numbers

The number arguments (point_adjustment, confidence, weight, expected_member_count, and point_adjustment / confidence in batch rows) accept JSON numbers and numeric strings. true and false are rejected (must be a number, not a boolean) instead of being read as 1 and 0. expected_member_count must be a whole number of at least 0.
A batch row's overwrite accepts only JSON true, false or null. Strings and numbers ("yes", "true", 1) are rejected (must be true, false or null) instead of opting the row into an overwrite.

Submission IDs

tool_get_assignment_submissions returns assignment-level Global Submission IDs.
Grading tools require Question Submission IDs. Get them from tool_list_question_submissions, tool_get_student_submission_map, tool_get_next_ungraded, or the regrade tools. A 404 from a grading tool usually means a Global Submission ID was passed.
When submissions.json is unavailable, tool_get_assignment_submissions reads the review-grades page. If that table has no recognizable Score or Graded column, graded status is reported as unknown (? rows, Graded: unknown or at least N/M (K unknown), with a ⚠️ warning) rather than read from a guessed column; unknown is not ungraded.

Write safety

The tools with a confirm_write parameter (the write kind, 11 of them) are the only tools that change Gradescope data. With the default confirm_write=False they return a preview ("Write confirmation required ...") and change nothing.
Previews describe exactly what confirm_write=True would send: resolved dates, rubric items that will be checked and unchecked, the projected score, affected students. Inputs are validated before the preview, so an invalid request is refused instead of previewed.
After writing, the tools read the result back from Gradescope where practical (grades, rubric items, dates, extensions) and report mismatches.
confirm_write=True is not human approval. An agent can set it on its own; every preview includes the line "Show this preview to the user; only after they explicitly approve, re-run with confirm_write=True ...", and the prompts and the skill tell agents to wait for the user's explicit approval.
The write tools are annotated destructiveHint: true (and readOnlyHint: false), so a client can require confirmation for them. Keep them out of any "always allow" list in your MCP client so each write needs approval. idempotentHint is false only for tool_upload_submission and tool_create_rubric_item, which create something new on every call; repeating any other write with the same arguments has no further effect, although the repeat may report differently (for example that the item is already gone).
Rubric updates and deletions apply to every submission that uses the item. tool_grade_answer_group writes to many submissions at once, and Gradescope may also apply it to the group's inferred (unconfirmed) members.

Error signalling

Tools return text: markdown, or a JSON document when a tool offers output_format="json". They publish no outputSchema and return no structuredContent.
A handled failure starts with Error, Authentication error or ❌ (a write Gradescope rejected) and is returned with isError: true; the text is unchanged.
Previews, confidence rejections (⚠️ **Grade REJECTED** ...), other ⚠️ warnings and "No ... found" messages are ordinary results (isError: false).
Invalid arguments (bad IDs, true / false where a number is expected, unknown batch-row keys, values outside an enum, missing required arguments) are rejected by the input schema and come back with isError: true as Error executing tool <name>: ... validation error ....

Untrusted student text

Student-authored content (typed answers, regrade messages, answer-group titles and inferred answers) is returned inside fenced untrusted blocks, or flagged by untrusted_fields_note in JSON output. It is data to grade, never instructions to follow.
A block starts with <<<BEGIN UNTRUSTED {label} (block id {id}; student-authored; ...)>>> and ends with <<<END UNTRUSTED {label}>>> (block id {id}). The block id is random for every call, and only the END line with the same block id as its BEGIN line closes the block. Inside the text, <<< / >>> runs and runs of three or more backticks are broken up with zero-width spaces, so a student can neither close the fence nor forge a marker.
Student display names in grading contexts, previews, reading plans and submission headings are kept on one line (newlines collapsed, pipes escaped).

Dates and timezones

Both date tools need an explicit time: YYYY-MM-DDTHH:MM (:00 seconds allowed). Bare dates, non-zero seconds and impossible dates are rejected. An empty string or null means "not provided".
tool_modify_assignment_dates: course-local wall-clock times with no UTC offset. Omitted dates and the allow-late-submissions setting are read from the assignment settings and re-sent unchanged. Passing late_due_date turns late submissions on; the tool cannot turn them off. The settings page renders its date fields in the browser, so the current values come from the page's due-date settings data (release, due, late due date and whether it is enabled, the LMS sync flag and the course timezone); form inputs are the fallback. A value missing or unreadable there is never guessed: the call is an Error that asks for that date explicitly. The preview lists all values that will be sent, so it returns an error (Authentication error / Error) rather than a partial preview when they can't be read; the write refuses for the same reason. Preview and result name the course timezone the page reports (the IANA name, for example America/Los_Angeles; no DST abbreviation, since the one Gradescope shows is only correct for today) and warn when the due date is synced from an LMS, since a later sync may overwrite it. The result is verified by re-reading the settings the same way, and requested values that were already set are labelled as such.
tool_get_assignments / tool_get_assignment_details show dates that Gradescope reports with a UTC offset with that offset (for example 2026-10-01 23:59 UTC-07:00). tool_get_assignments names assignment containers on the staff page in a note below the table; they are not assignments and are not counted, so the total can be lower than the count tool_list_courses shows.
tool_get_extensions names the course timezone above the table and shows each date as course-local time and the UTC instant Gradescope stores (2026-10-01 23:59 PDT = 2026-10-02T06:59:00Z), plus an Other Settings column (for example time_limit=135, visible=true). Either form of a date can be passed to tool_set_extension. When the course timezone is unknown, the line says so and dates are shown as stored.
tool_set_extension: dates without an offset are wall-clock times in the course timezone Gradescope reports on the extensions page, never the server's timezone. The timezone argument (an IANA name) is needed only when Gradescope reports no course timezone; if it is given and differs from the timezone Gradescope reports, the call is an Error naming both and nothing is sent. When the page reports several timezones, or one the server doesn't know, a timezone argument can't be checked and is refused too (the Error names what was reported); give the dates with a UTC offset then. Dates with an offset (Z, -07:00) are absolute. Don't mix the two styles. When timezone stood in for an unreported course timezone and the read-back after the write reports a different one, the result is a ⚠️ warning that dates without an offset were resolved in the wrong zone. Dates must be in order (release <= due <= late due), including dates kept from the current extension.
tool_set_extension sends the student's whole extension: the requested dates replace the current ones, every other current setting (other dates, a time limit, ...) is re-sent unchanged, and visible=true is always sent. Existing dates don't need to be passed again. The preview lists every current and outgoing setting with each date's resolved UTC instant; preview and write return an error when the extensions page or the login is unavailable. When the current extension has visible=false, preview and result list visible: false → true instead of saying that the write changes nothing. After writing, the extension is read back and any setting Gradescope removed or changed is reported (⚠️).
Confirmed date changes to one assignment, and confirmed extension changes for one student, run one at a time within the server process. A call that waits more than 300 s for another one returns an Error and changes nothing.

Grades and confidence

rubric_item_ids is the exact set of items to check; every other item is unchecked. In tool_apply_grade and batch rows, null keeps the current rubric state and [] clears it. In tool_grade_answer_group the list is required.
Every rubric item ID must be in the question's live rubric; otherwise nothing is sent (tool_apply_grade_batch refuses the whole batch).
confidence (optional): below 0.6 the grade is not written; 0.6 to 0.8 inclusive it is written but flagged NEEDS HUMAN REVIEW; above 0.8 it is normal. NaN and infinite values are rejected.
Already graded submissions are not overwritten by default, and an overwrite approval covers only the grades the user saw. tool_apply_grade refuses one (Error: submission ... is already graded) unless overwrite_graded=True. tool_apply_grade_batch has no batch-wide flag: a graded row is skipped unless that row has "overwrite": true, and the preview refuses "overwrite": true on a row that is not graded or already holds exactly the requested grade (there it could only overwrite a grade entered after the preview). Set either only after the user approved overwriting those grades. The graded state is re-read when the write runs, so a grade entered after the preview (for example by another grader) is protected too: the batch lists such rows under "Not written: already graded at write time", whatever the other rows carry. The result names every grade it overwrote. A graded submission that already holds exactly the requested grade is reported as such, and nothing is sent.
The grade is posted to the save URL of the grading page Gradescope serves. If that page belongs to another submission, nothing is sent: tool_apply_grade returns an Error, the batch preview refuses the batch, and at write time the row fails.
tool_apply_grade_batch takes at most 50 rows per call (maxItems in the input schema); a larger batch is refused before any request, so split it. Rows accept only submission_id (required and unique; "031" and "31" are the same row), rubric_item_ids, point_adjustment, comment, confidence and overwrite. The preview loads every row and marks already graded rows as SKIPPED (or OVERWRITTEN when the row has "overwrite": true); execution re-reads each row before saving it and reports the scores read back from Gradescope. Leave rows the preview marked SKIPPED out of the confirmed call: execution cannot know what the preview showed, so such a row is written if its grade was cleared in the meantime.

Answer groups

tool_grade_answer_group refuses (with an Error listing them) when any confirmed or inferred member is already graded, unless overwrite_graded=True. Set that only with the user's approval. Its preview then prints expected_graded_ids, the graded members whose grades the write overwrites; confirm_write=True over graded members is refused without that list, and refused when the members graded by then differ from it (for example a member graded after the preview). The result names the members whose grades were overwritten.
The grade page must belong to the requested group. A redirect to another group's page (or to a page that does not name the group), a page for another answer_group, or a save URL outside the course and question or through another group's confirmed member refuses the write before anything is sent.
Gradescope serves a group's grade page by redirecting to its representative submission in group mode, whose save URL already ends in /save_many_grades. That URL is used only when the page is in group mode for the requested group and saves through its own submission, which must be a confirmed member of the group. A save URL ending in /save_grade is still rewritten to /save_many_grades; any other URL is refused.
A group with no confirmed members is refused before its grade page is fetched: Gradescope has no grading page for it (its grade URL redirects to the answer-grouping overview). The Error lists the inferred members; confirm the members in Gradescope's answer-grouping UI or grade the submissions individually. A grade page that lands on that overview for another reason is reported as such.
Pass the member count from the preview as expected_member_count together with confirm_write=True; the write aborts if the group's membership changed since the preview.
rubric_item_ids=[] clears every rubric item for every member and is allowed only together with a point adjustment or comment.

Uploads

tool_upload_submission uploads as the logged-in account; each call creates a new submission. Each path must be an absolute path to a regular file of at most 100 MB. Hidden files and directories and credential-like names (keys, .env, ...) are refused. When GRADESCOPE_MCP_UPLOAD_ROOT is set, files must resolve inside one of its directories. When it is not set, symbolic links and files under system directories (/etc, /proc, /run, ...) are refused. The preview lists each file's size and SHA-256 and the expected_sha256 list to pass back with confirm_write=True. When it is passed, a file whose content changed since the preview makes the call an Error and nothing is uploaded. Without it, the result says the content was not checked. Each file is read once, and the bytes read are the ones hashed and sent.

Before uploading, the tool reads the assignment page to note the account's existing submissions. Success is reported only when all of these hold:

Gradescope answers the upload request itself with a redirect to a submission of this assignment (/courses/<cid>/assignments/<aid>/submissions/<id>).
That submission was not among the existing ones.
The final page is that submission's page, or a page below it such as the PDF page-selection step.
The final page shows no visible error-styled message (alert-danger, alert-error, flash-error and the like). Hidden elements, JavaScript templates and <noscript> content are ignored.

Any other outcome is ❌ Upload not confirmed, with the redirect target, the final page and any message Gradescope showed (an error message is quoted on its own line). A visible message that is not styled as an error or a success (a warning, a bare role="alert") does not turn a confirmed upload into a failure: the success result quotes it under a ⚠️ line. A rejected upload that ends on an older submission is therefore not reported as a success. Check the assignment in Gradescope before uploading again, since every upload creates a new submission.

Scoring direction

Gradescope questions use positive or negative scoring.
When Gradescope does not report it, tool_get_question_rubric, the grading context and the regrade detail show it as unknown (for example unknown (not reported by Gradescope; projections assume negative); JSON scoring_type: null plus scoring_type_note) instead of assuming a direction, and the grade previews warn that their projected scores assume deduction. No tool can resolve it: ask the user or check the question's scoring settings in Gradescope.
Rubric weights are positive numbers in both modes; the scoring type decides whether a checked item adds or deducts points. Negative weights are rejected unless allow_negative=True is passed deliberately.

Scanned / handwritten assignments

Structured reference answers are often unavailable. This is expected, not necessarily a parsing failure.
Students often tag the wrong pages. The workflow helpers use crop regions, the rest of the crop page, adjacent pages, then every other page, plus rubric text and user-provided reference notes.
tool_cache_relevant_pages streams each page image and drops a page that exceeds 25 MB or takes more than 120 s (from the request on, also for a Gradescope-hosted URL answered as HTML); failed pages are listed and the rest are cached. A Gradescope-hosted page that turns out to be the logged-out page is a session expiry, as for any other request.
Without a usable assignment_id, the workflow helpers find the question's assignment by scanning the course: unreadable assignments (no access, non-JSON pages) are skipped, while three non-JSON pages in a row or an authentication error stop the scan with an error.
Readiness scores describe how much pre-read context exists (prompt, reference, rubric, crop regions, located student work). They are not grading confidence. Scanned exams usually show partially_ready.

Local cache

Root: $GRADESCOPE_MCP_CACHE_DIR if set, else $XDG_RUNTIME_DIR/gradescope-mcp (when that runtime directory exists and belongs to you), else <system temp dir>/gradescope-mcp-<uid>.
Directories are created with mode 0700 and files with mode 0600, written atomically without following symlinks. The workflow tools print the real path of every file they write.
The server refuses a root that is a symlink, owned by another user, or accessible to group/other: the workflow tools return an Error and the server logs the problem at startup. Fix it with chmod 700 <dir> or point GRADESCOPE_MCP_CACHE_DIR at another directory.
At startup the server points its own TMPDIR/TEMP/TMP at the cache root and XDG_CACHE_HOME at a subdirectory of it, so temporary files stay private.
The cache is ephemeral: $XDG_RUNTIME_DIR is normally cleared at logout, and the temp-directory fallback may be cleared at reboot. Do not rely on earlier artifacts in a new session.

Configuration

Variable	Required	Meaning
`GRADESCOPE_EMAIL`	yes	Gradescope account email
`GRADESCOPE_PASSWORD`	yes	Gradescope account password
`GRADESCOPE_MCP_CACHE_DIR`	no	Private cache root (see Local cache); must be owned by you with mode 0700
`GRADESCOPE_MCP_HTTP_TIMEOUT`	no	Read timeout in seconds for Gradescope requests (default 60); the connect timeout is `min(10, value)`. Invalid values are ignored with a warning
`GRADESCOPE_MCP_UPLOAD_ROOT`	no	Absolute paths of existing directories, separated by `os.pathsep` (`:` on Linux/macOS, `;` on Windows), that upload files must resolve inside

At startup, python -m gradescope_mcp (and the gradescope-mcp console script) loads .env files with python-dotenv from these places only:

.env in the current working directory;
.env in the gradescope-mcp source checkout the server runs from (this repository's src/gradescope_mcp layout, recognized by its pyproject.toml).

Variables already set in the environment (for example in the MCP client's env block) always win, and the working directory's .env wins over the checkout's. Parent directories are never searched, so a stray .env in your home directory or next to an installed package is ignored. On Linux and macOS a .env owned by another user (other than root) or writable by everyone is skipped. The server logs which files it loaded or skipped. With a non-editable install, start the server in a directory that holds the .env, or pass the variables through the client configuration.

Authentication

Credentials come only from GRADESCOPE_EMAIL and GRADESCOPE_PASSWORD. The server logs in itself and POSTs them as a form body to /login (gradescopeapi would put them in the URL query string). Error messages and logs never contain them.
A login that Gradescope answers without logging in starts a cooldown. Until it ends, calls with the same credentials fail immediately with the same Authentication error: ..., which ends with "Not trying to log in again for .", without contacting Gradescope:
- invalid credentials (Gradescope shows the login form again or says the email or password is wrong): 10 minutes;
- HTTP 429 or 5xx: Gradescope's Retry-After, or 1 minute without one;
- a "too many login attempts" page: 5 minutes (or Retry-After);
- any other rejection (login rejected (HTTP <status>), no CSRF token after login, ...): 1 minute.
A Retry-After wait is capped at 15 minutes. Network errors start no cooldown. Before every login attempt the server re-reads GRADESCOPE_EMAIL / GRADESCOPE_PASSWORD from the .env files it loaded at startup, so after fixing them in .env the next call logs in with the new credentials (no cooldown applies to changed credentials) — no restart needed. Credentials set in the MCP client's env block take precedence over .env and still need a server restart to change.
Every request has a default timeout of 10 s to connect and 60 s to read (see GRADESCOPE_MCP_HTTP_TIMEOUT), so a stalled connection fails the call instead of hanging it.
When Gradescope's session expires during a call (a redirect to the login page, the login page itself, a 401 "must be logged in", or the logged-out home page with the login form and no logout link, for example after a redirect to /), the tool or resource logs in again and re-runs once.
A call is not re-run if Gradescope had already accepted a write during it: a re-run could repeat the write, or find it done and report that nothing changed. The result then ends with a "⚠️ The Gradescope session expired during this call after Gradescope had accepted N write request(s) ..." notice. Gradescope did receive those writes; anything the result reports as failed or not read back is unconfirmed, so check it with the read tools before retrying it.
If the session expires again during the re-run, the result depends on whether Gradescope accepted a write during the re-run:
- It did: the re-run's output is returned with the same "⚠️ ... accepted N write request(s) ..." notice. This is not an error result (isError is false unless the output itself starts with an error), so look for the notice rather than relying on isError. If the re-run raised instead of returning output, the result is Authentication error: Gradescope session expired during the call after Gradescope had accepted N write request(s); ....
- It did not: the result is Authentication error: Gradescope session expired and re-login did not restore access. (isError: true), followed by the output of the first attempt (or of the re-run, if the first attempt raised), labelled as possibly incomplete. If neither run returned output, the error stands alone.
Only email/password login is supported.

Architecture

Entry points

src/gradescope_mcp/__main__.py: main() loads the .env files (see Configuration), sets up the private cache environment, configures logging, and runs the MCPServer (mcp v2) over stdio. The gradescope-mcp console script calls the same main(); importing the module has no side effects.
src/gradescope_mcp/server.py: registers all tools, resources and prompts. Tools are registered with gs_tool(annotations) and resources with gs_resource(uri); both add session recovery, and gs_tool adds the annotations, the title and the isError mapping. It also defines the argument types (GradescopeID, Number, Count) and the typed GradeRow batch rows.

Runtime

mcp v2 runs these sync tool functions on worker threads, so tool calls can run concurrently and pings are answered while a tool waits on Gradescope. A cancelled or timed-out call is not interrupted; its thread runs to the end (see Known Caveats).
src/gradescope_mcp/auth.py: one shared GSConnection behind a lock; form-body login, failed-login cooldowns, TimeoutHTTPAdapter default timeouts, a response hook that raises SessionExpiredError and counts the writes Gradescope accepted during the call, and with_session_recovery, which re-runs a call once after an expiry unless a write was accepted.
src/gradescope_mcp/cache.py: the private per-user cache root and safe artifact writes.
src/gradescope_mcp/envfiles.py: which .env files are loaded, in what precedence, and refresh_credentials(), which re-reads the credentials from those files before each login attempt.

Tool modules

tools/courses.py: course listing and roster parsing
tools/assignments.py: assignment listing, date edits (and the shared date parser and per-object write lock), rename, autograder image
tools/submissions.py: uploads, submission listing, per-student submission reads, grader discovery
tools/extensions.py: extension reads and writes
tools/grading.py: outline parsing, score exports, grading progress, student submission links
tools/grading_ops.py: grading context, grade writes (single and batch), rubric CRUD, question-submission discovery, navigation
tools/grading_workflow.py: grading artifacts, answer keys, readiness, page caching, smart reading
tools/answer_groups.py: answer-group inspection and batch writes
tools/regrades.py: regrade listing and detail
tools/statistics.py: assignment statistics
tools/lms_export.py: Canvas / Brightspace gradebook import CSV export
tools/common.py: shared helpers (rubric-ID normalization, untrusted-text blocks, markdown escaping, one-line display names, page selection)
tools/safety.py: the standard write-preview message

Quick Start

1. Prerequisites

Python 3.10+
uv

2. Install

git clone https://github.com/Yuanpeng-Li/gradescope-mcp.git
cd gradescope-mcp
cp .env.example .env

Then edit .env with your Gradescope credentials (and any optional settings).

3. Run locally

uv run python -m gradescope_mcp

4. Configure an MCP client

Example client configuration:

{
  "mcpServers": {
    "gradescope": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/gradescope-mcp",
        "python",
        "-m",
        "gradescope_mcp"
      ],
      "env": {
        "GRADESCOPE_EMAIL": "your_email@example.com",
        "GRADESCOPE_PASSWORD": "your_password"
      }
    }
  }
}

Credentials in a client configuration file are stored in plain text; keep that file private (this repository ignores .mcp.json and .env).

5. Debug with MCP Inspector

npx @modelcontextprotocol/inspector uv run python -m gradescope_mcp

6. Run tests

uv run pytest -q

The tests are offline: they use fakes, a per-test cache directory and no credentials.

Assisted Grading Skill

The repository includes one skill:

gradescope-assisted-grading

It is intended for:

preview-first grading
rubric review before mutation
scanned exam grading
answer-group triage
explicit human approval before any grade write

Install the skill

Link (or copy) the skill directory into your client's skills directory. For Claude Code, personal skills live in ~/.claude/skills/<name>/ and project skills in .claude/skills/<name>/ of the project you work in.

mkdir -p ~/.claude/skills
ln -s "$(pwd)/skills/gradescope-assisted-grading" ~/.claude/skills/gradescope-assisted-grading

If you prefer copying (re-copy after updating this repository):

mkdir -p ~/.claude/skills
cp -R skills/gradescope-assisted-grading ~/.claude/skills/

For other clients, put the directory wherever that client loads skills from.

Verify installation

ls ~/.claude/skills/gradescope-assisted-grading
head -n 5 ~/.claude/skills/gradescope-assisted-grading/SKILL.md

In Claude Code, invoke it with /gradescope-assisted-grading or by asking "Use the gradescope-assisted-grading skill".

Project Structure

gradescope-mcp/
├── .env.example
├── .gitignore
├── .python-version
├── AGENT.md
├── DEVLOG.md
├── LICENSE
├── README.md
├── pyproject.toml
├── uv.lock
├── skills/
│   └── gradescope-assisted-grading/
│       └── SKILL.md
├── src/
│   └── gradescope_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── auth.py
│       ├── cache.py
│       ├── envfiles.py
│       ├── server.py
│       └── tools/
│           ├── __init__.py
│           ├── answer_groups.py
│           ├── assignments.py
│           ├── common.py
│           ├── courses.py
│           ├── extensions.py
│           ├── grading.py
│           ├── grading_ops.py
│           ├── grading_workflow.py
│           ├── lms_export.py
│           ├── regrades.py
│           ├── safety.py
│           ├── statistics.py
│           └── submissions.py
└── tests/
    ├── conftest.py
    ├── test_answer_groups.py
    ├── test_assignments_and_grading_ops.py
    ├── test_auth.py
    ├── test_common.py
    ├── test_dates_extensions_submissions.py
    ├── test_docs_consistency.py
    ├── test_extensions_and_answer_key.py
    ├── test_grading_ops_fixes.py
    ├── test_grading_workflow.py
    ├── test_live_fixes.py
    ├── test_lms_export.py
    ├── test_p0_fixes.py
    ├── test_page_selection.py
    ├── test_read_side_fixes.py
    ├── test_round3_runtime.py
    ├── test_server_mcp.py
    ├── test_session_recovery.py
    ├── test_workflow_fixes.py
    └── test_write_safety.py

Development Notes

AGENT.md summarizes the architecture and the rules for changing tools.
DEVLOG.md records the implementation history.
tests/test_docs_consistency.py checks this file, AGENT.md and the skill against the registered tools, resources, prompts and environment variables.
If you test writes against a real account, keep the log of those changes outside the repository. OPERATIONS_LOGS/ is gitignored for that purpose and is not part of the repository.

Known Caveats

Gradescope behavior differs across assignment types; several tools rely on HTML parsing or reverse-engineered endpoints, and some write behavior (for example how save_many_grades treats inferred members) can't be verified offline. The tools choose the conservative option and say so. The pages the date and group-grading writes read (the settings page's due-date data, the group grade page's redirect to a group-mode submission page) were checked read-only against a live account; the writes themselves have not been run against one.
Roster parsing uses a custom parser because the upstream library parser is unreliable when sections are present.
Some assignment types do not support the extensions API even for staff users, and removing an extension is not supported. tool_set_extension refuses when the extensions page has neither the extensions table nor an existing extension; if Gradescope renders such a page for an assignment without extensions, add the first one in the web UI.
Scanned assignments usually do not provide a structured answer key.
Question grading requires Question Submission IDs, not assignment-level Global Submission IDs.
mcp runs each tool call on a worker thread and does not stop it when the client cancels or times out. The call runs to the end (a batch writes its remaining rows, at most 50) and the client never sees its result. After a timed-out write, re-read the affected submissions or settings before retrying.
Date and extension writes are serialized only within one server process. Each confirmed write re-reads the current settings, but a change made elsewhere (another server process, the web UI) between that read and the write can still be overwritten.

Available Tools

33 tools

tool_apply_gradeA

Apply a grade to a student's question submission.

Can apply/remove rubric items, set point adjustments, and add comments.
**WARNING**: This modifies student grades.

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID.
    submission_id: The question submission ID.
    rubric_item_ids: List of rubric item IDs to apply (checked). Items NOT
        in this list will be unchecked. Pass None to keep unchanged.
    point_adjustment: Submission-specific point adjustment. Pass None to keep.
    comment: Grader comment. Pass None to keep unchanged.
    confidence: Agent's self-assessed grading confidence (0.0-1.0).
        Below 0.6 = rejected. 0.6-0.8 = warning. Above 0.8 = OK.
        Pass None to skip confidence gating (manual mode).
    confirm_write: Must be True to save the grade.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`question_id`	Yes
`submission_id`	Yes
`rubric_item_ids`	No
`point_adjustment`	No
`comment`	No
`confidence`	No
`confirm_write`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by disclosing: 1) the destructive nature ('This modifies student grades'), 2) the confidence gating behavior with specific thresholds, 3) the manual mode option, and 4) the safety mechanism (confirm_write). It doesn't mention rate limits or authentication requirements, but covers key behavioral aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: purpose statement first, capabilities listed, warning highlighted, then detailed parameter explanations. Every sentence earns its place, with no redundant information. The bullet-like parameter explanations are clear without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 parameters, destructive operation, no annotations) and the presence of an output schema, the description is complete. It covers purpose, behavioral warnings, parameter semantics, and usage context. The output schema existence means return values don't need explanation in the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining all 8 parameters. It clarifies: rubric_item_ids behavior (items not in list become unchecked), point_adjustment/comment/confidence None semantics (keep unchanged/skip), confidence thresholds with specific ranges, and confirm_write's safety role. This adds substantial meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Apply a grade') and target resource ('student's question submission'), distinguishing it from sibling tools like tool_create_rubric_item or tool_update_rubric_item. It also lists specific capabilities: applying/removing rubric items, setting point adjustments, and adding comments.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through the warning about modifying student grades and the confirm_write parameter, but doesn't explicitly state when to use this tool versus alternatives like tool_grade_answer_group or tool_update_rubric_item. It provides some context about confidence gating but lacks explicit guidance on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_assess_submission_readinessA

Assess whether an agent should auto-grade a specific submission.

Returns a crop-first read plan, fallback rules for whole-page/adjacent-page
reads, and a coarse confidence score that can be used to skip or escalate.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.
    question_id: The question ID.
    submission_id: The question submission ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes
`question_id`	Yes
`submission_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses behavioral traits such as returning a 'crop-first read plan', 'fallback rules', and a 'coarse confidence score', which adds context about outputs. However, it lacks details on permissions, rate limits, or side effects, which are important for a tool that might influence grading decisions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the purpose, followed by details on returns and parameters. Every sentence adds value without redundancy, making it efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (assessing submission readiness) and the presence of an output schema (which likely covers return values), the description is mostly complete. It explains the purpose, parameters, and key outputs like confidence scores. However, without annotations, it could benefit from more behavioral context, such as error handling or performance implications.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It lists the four parameters (course_id, assignment_id, question_id, submission_id) and briefly explains they are IDs for Gradescope entities, adding meaning beyond the schema. However, it does not provide format details or examples, leaving some gaps in parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to assess whether an agent should auto-grade a specific submission. It specifies the verb 'assess' and the resource 'submission readiness', distinguishing it from siblings like tool_apply_grade (which applies grades) or tool_get_submission_grading_context (which retrieves context).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for auto-grading decisions but does not explicitly state when to use this tool versus alternatives. It mentions returns like 'crop-first read plan' and 'coarse confidence score', suggesting it's for pre-grading assessment, but lacks explicit guidance on prerequisites or comparisons to siblings like tool_smart_read_submission or tool_get_next_ungraded.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_cache_relevant_pagesA

Download the crop page and neighboring pages to /tmp for local review.

This is useful for scanned exams where the prompt is only available in page
images and where agents may need to inspect adjacent pages before grading.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.
    question_id: The question ID.
    submission_id: The question submission ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes
`question_id`	Yes
`submission_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the tool downloads files to /tmp for local review, which implies read-only caching behavior. However, it doesn't mention permissions needed, rate limits, file cleanup, or error handling, leaving gaps for a tool that interacts with file systems.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core action, followed by usage context and parameter list. Every sentence adds value without redundancy, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters with 0% schema coverage and no annotations, the description does a good job explaining purpose and usage. The presence of an output schema means return values don't need description. However, it lacks details on error cases or system interactions, which could be important for a file-download tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It lists all four parameters (course_id, assignment_id, question_id, submission_id) in the Args section, providing basic semantics. However, it doesn't explain what these IDs represent or their formats, which limits understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool downloads specific pages to a local directory for review, with a specific verb ('Download') and resource ('crop page and neighboring pages'). It distinguishes from siblings by focusing on page caching rather than grading or management tasks, though it doesn't explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: for scanned exams where prompts are in page images and agents need to inspect adjacent pages before grading. It doesn't explicitly state when not to use it or name specific alternatives among siblings, but the context is well-defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_create_rubric_itemA

Create a new rubric item for a question.

**WARNING**: Changes the rubric for ALL submissions.

Weight semantics depend on the question's scoring type:
- **Positive scoring:** Items ADD points (use positive weights).
- **Negative scoring:** Items DEDUCT from max (use negative weights).

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID.
    description: Rubric item description.
    weight: Point value — see scoring-type note above.
    confirm_write: Must be True to create the rubric item.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`question_id`	Yes
`description`	Yes
`weight`	Yes
`confirm_write`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by disclosing important behavioral traits: the destructive nature ('WARNING: Changes the rubric for ALL submissions'), weight semantics based on scoring type, and the confirm_write safety mechanism. It doesn't cover rate limits or authentication needs, but provides substantial operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Perfectly structured and front-loaded: purpose statement first, critical warning next, weight semantics explanation, then parameter details. Every sentence earns its place with zero waste. The bullet formatting enhances readability without verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations, 5 parameters, and 0% schema coverage, the description is remarkably complete. It covers purpose, behavioral implications, parameter semantics, and critical warnings. The presence of an output schema means return values don't need explanation, making this description fully adequate for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Given 0% schema description coverage, the description compensates excellently by explaining all 5 parameters in the Args section. It adds crucial semantic context beyond schema types: course_id and question_id identify resources, description is the rubric content, weight has scoring-type dependencies, and confirm_write serves as a safety flag. This fully addresses the schema coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Create a new rubric item') and resource ('for a question'), distinguishing it from sibling tools like tool_delete_rubric_item and tool_update_rubric_item. It provides precise verb+resource pairing with no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use this tool (creating rubric items) and includes a critical warning about scope ('Changes the rubric for ALL submissions'), but doesn't explicitly mention when NOT to use it or name alternatives like tool_update_rubric_item for modifications.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_delete_rubric_itemA

Delete a rubric item from a question.

**WARNING**: Removes the item from ALL submissions and recalculates scores.

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID.
    rubric_item_id: The rubric item ID to delete.
    confirm_write: Must be True to delete the item.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`question_id`	Yes
`rubric_item_id`	Yes
`confirm_write`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the destructive nature ('WARNING: Removes the item from ALL submissions and recalculates scores'), which is crucial for a mutation tool. It also mentions the 'confirm_write' parameter as a safety measure, adding context beyond basic functionality.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose and critical warning, followed by a clear parameter list. Every sentence adds value, with no wasted words, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (destructive mutation) and lack of annotations, the description does a good job covering purpose, impact, and parameters. Since an output schema exists, it need not explain return values. However, it could benefit from more details on prerequisites or error conditions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It lists all four parameters with brief explanations (e.g., 'The Gradescope course ID'), which adds meaning beyond the schema's titles. However, it does not provide detailed semantics like format examples or constraints, leaving some gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Delete a rubric item from a question'), identifies the resource ('rubric item'), and distinguishes it from siblings like 'tool_create_rubric_item' and 'tool_update_rubric_item' by specifying deletion rather than creation or modification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (to delete a rubric item) and includes a warning about the impact ('Removes the item from ALL submissions and recalculates scores'), which helps guide usage. However, it does not explicitly mention when not to use it or name specific alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_export_assignment_scoresA

Export per-question scores for an assignment.

Returns a summary table with student names, total scores, statistics,
and per-question breakdowns. Requires instructor/TA access.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses access requirements ('Requires instructor/TA access') and output behavior ('Returns a summary table...'), which is helpful. However, it misses details like rate limits, error handling, or whether the export is destructive (e.g., file generation). The description doesn't contradict annotations, as none exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose, followed by output details, access requirements, and parameter explanations in a logical flow. Every sentence adds value without redundancy, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no annotations, but has an output schema), the description is reasonably complete. It covers purpose, output, access needs, and parameter semantics. With an output schema present, it doesn't need to detail return values, though it could mention behavioral aspects like side effects or limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining that 'course_id' is 'The Gradescope course ID' and 'assignment_id' is 'The assignment ID,' providing context beyond the schema's generic titles. This clarifies the parameters' roles, though it could specify format or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'Export per-question scores for an assignment' with specific verb ('Export') and resource ('per-question scores for an assignment'). It distinguishes itself from siblings like 'tool_get_assignment_statistics' by focusing on export functionality, though it doesn't explicitly contrast with all related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some usage context with 'Requires instructor/TA access,' indicating prerequisites. However, it lacks explicit guidance on when to use this tool versus alternatives like 'tool_get_assignment_statistics' or 'tool_get_assignment_submissions,' leaving the agent to infer based on the 'export' focus.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_answer_group_detailA

Get detail for one answer group: members, crops, graded status.

Use this to inspect what answers are in a group before batch-grading.

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID.
    group_id: The answer group ID.
    output_format: "markdown" or "json" for structured output.

ParametersJSON Schema

Name	Required	Default
`course_id`	Yes
`question_id`	Yes
`group_id`	Yes
`output_format`	No	markdown

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool is for inspection ('inspect what answers are in a group'), implying it's read-only, but doesn't explicitly state this or cover other behavioral aspects like authentication needs, rate limits, or error handling. It adds some context about the output format but lacks comprehensive behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear purpose statement, usage guideline, and parameter list in just a few sentences. Every sentence adds value without redundancy, making it easy to parse and front-loaded with essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (4 parameters, no annotations, but with an output schema), the description is reasonably complete. It covers purpose, usage, and parameters adequately. The presence of an output schema means the description doesn't need to explain return values, but it could benefit from more behavioral context (e.g., read-only confirmation).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description lists all four parameters with brief explanations, adding meaning beyond the schema (which has 0% description coverage). It clarifies that 'output_format' accepts 'markdown' or 'json' for structured output, which is not evident from the schema alone. However, it doesn't provide deeper semantics for IDs (e.g., format or sourcing), leaving some gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get detail for one answer group') and the resources involved ('members, crops, graded status'). It distinguishes from sibling tools like 'tool_get_answer_groups' (which likely lists groups) and 'tool_grade_answer_group' (which performs grading), making the purpose unambiguous and well-differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: 'Use this to inspect what answers are in a group before batch-grading.' This provides clear context and distinguishes it from grading tools like 'tool_grade_answer_group', offering practical guidance for the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_answer_groupsA

List all answer groups for a question (AI-Assisted Grading).

Shows clusters of similar student answers. Grade one group to
grade all members at once — much more efficient than 1-by-1.

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID.
    output_format: "markdown" or "json" for structured output.

ParametersJSON Schema

Name	Required	Default
`course_id`	Yes
`question_id`	Yes
`output_format`	No	markdown

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses that this is a read operation (listing/showing clusters) and mentions the efficiency benefit of batch grading. However, it doesn't cover important behavioral aspects like authentication requirements, rate limits, pagination, error conditions, or what happens if no groups exist. The description adds some context but leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with three sentences and a parameter section. Each sentence adds value: the core purpose, the clustering concept, and the efficiency benefit. The parameter explanations are brief but clear. No wasted words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (which handles return values), no annotations, and moderate complexity, the description does well. It covers purpose, usage context, and parameter semantics. However, for a tool with no annotations, it could better address behavioral aspects like authentication, error handling, and performance characteristics to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides clear semantic meaning for all three parameters: course_id and question_id identify the specific question, and output_format specifies the response structure. The description explains what these parameters do beyond their schema titles, though it doesn't provide format details or examples for the IDs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('List all answer groups for a question') and resource ('AI-Assisted Grading'), distinguishing it from siblings like tool_get_answer_group_detail (which likely shows details of one group) or tool_grade_answer_group (which applies grades). It explicitly mentions clustering of similar student answers and the efficiency benefit of grading by group.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool: for listing answer groups to enable efficient batch grading. It distinguishes from 1-by-1 grading alternatives and implies usage in AI-assisted grading workflows. The context of 'Grade one group to grade all members at once' clearly indicates its purpose versus individual grading tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_assignment_detailsB

Get detailed information about a specific assignment.

Returns the assignment name, dates, submission status, and grade.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID (found via get_assignments).

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns specific details (name, dates, status, grade), which adds some behavioral context. However, it lacks information on permissions required, rate limits, error handling, or whether it's a read-only operation (implied by 'Get' but not explicit). For a tool with no annotations, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the purpose, followed by return details and parameter explanations. Every sentence adds value, with no redundant information. However, the structure could be slightly improved by more clearly separating usage guidance from parameter semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (which likely defines return values), the description doesn't need to explain returns in detail. However, with no annotations and 0% schema coverage for inputs, the description partially compensates with parameter context but lacks behavioral details like auth needs or error cases. For a simple read operation, it's adequate but has clear gaps in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining that 'course_id' is a 'Gradescope course ID' and 'assignment_id' is 'found via get_assignments', providing context beyond the schema's generic titles. This clarifies the source and usage of parameters, though it doesn't detail formats or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get detailed information about a specific assignment.' It specifies the verb ('Get') and resource ('assignment'), and lists the returned details (name, dates, status, grade). However, it doesn't explicitly differentiate from siblings like 'tool_get_assignments' (which lists assignments) or 'tool_get_assignment_statistics' (which might provide aggregated data), though the focus on 'detailed information' for a 'specific' assignment implies some distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by stating it returns details for a 'specific assignment' and references 'tool_get_assignments' to find the assignment_id, suggesting a workflow. However, it doesn't explicitly state when to use this tool versus alternatives like 'tool_get_assignment_submissions' or 'tool_get_assignment_outline', nor does it provide exclusions or prerequisites beyond needing IDs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_assignment_gradersB

Get the list of graders assigned to a specific question (instructor/TA only).

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID within the assignment.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`question_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions access control ('instructor/TA only'), which is useful, but does not disclose other traits such as whether this is a read-only operation, potential rate limits, error conditions, or what the output looks like (though an output schema exists). For a tool with no annotations, this leaves significant gaps in understanding its behavior beyond basic purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the purpose and access restriction, followed by a structured 'Args' section. There is no wasted text, and it efficiently conveys key information in two parts. However, it could be slightly more polished by integrating the args into the flow, but it remains clear and concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 2 parameters, no annotations, but an output schema exists, the description is reasonably complete. It covers the purpose, access control, and parameters, and the output schema will handle return values. However, it lacks details on behavioral aspects like error handling or usage nuances, which could be important for a tool with no annotations. Overall, it's adequate but not fully comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description includes an 'Args' section that lists and briefly describes the two parameters ('course_id' and 'question_id'), adding meaning beyond the input schema, which has 0% description coverage. However, it does not provide detailed semantics like format examples or constraints (e.g., what a valid ID looks like). With low schema coverage, the description compensates partially but not fully, aligning with the baseline expectation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get the list of graders assigned to a specific question' with the qualification '(instructor/TA only)'. It specifies the verb ('Get'), resource ('list of graders'), and scope ('assigned to a specific question'). However, it does not explicitly differentiate from sibling tools like 'tool_get_course_roster' or 'tool_get_assignment_details', which might also involve retrieving course-related data, so it lacks sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying '(instructor/TA only)', indicating it's for authorized users only, but it does not provide explicit guidance on when to use this tool versus alternatives. For example, it doesn't clarify if this is for grading management versus other grader-related tools (though none are listed as siblings). The context is clear but lacks exclusions or named alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_assignment_outlineA

Get the question/rubric outline for an assignment.

Returns the hierarchical question structure with IDs, types, weights, and
question text. Essential for understanding how an assignment is structured.
Requires instructor/TA access.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses access requirements ('Requires instructor/TA access') and hints at the return content ('hierarchical question structure with IDs, types, weights, and question text'), but lacks details on rate limits, error handling, or whether it's read-only (implied by 'Get' but not explicit).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the purpose, followed by key details on returns and access, with a brief parameter section. Every sentence adds value without redundancy, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (2 parameters, no annotations, but has an output schema), the description is mostly complete. It covers purpose, usage context, and parameter semantics, but since the output schema exists, it need not explain return values. A minor gap is lack of behavioral details like error cases or performance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining that course_id is 'The Gradescope course ID' and assignment_id is 'The assignment ID', clarifying their roles beyond the schema's generic titles. However, it does not specify format or constraints (e.g., numeric vs. string IDs).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get the question/rubric outline') and resource ('for an assignment'), distinguishing it from siblings like tool_get_assignment_details or tool_get_question_rubric by focusing on hierarchical structure rather than general details or specific rubric items.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear context by stating this is 'Essential for understanding how an assignment is structured' and 'Requires instructor/TA access', which helps guide usage. However, it does not explicitly mention when not to use it or name alternatives among siblings, such as tool_get_assignment_details for broader information.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_assignmentsA

Get all assignments for a specific Gradescope course.

Returns a table of assignments with names, IDs, dates, status, and grades.

Args:
    course_id: The Gradescope course ID (found via list_courses).

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool returns a table with specific fields (names, IDs, dates, status, and grades), which adds value beyond the input schema. However, it doesn't cover critical behavioral aspects such as whether this is a read-only operation, potential rate limits, authentication needs, or error handling, leaving significant gaps for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the purpose, the second describes the return format, and the third provides parameter guidance. Every sentence earns its place with no wasted words, making it efficient and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one parameter) and the presence of an output schema (which handles return values), the description is mostly complete. It covers purpose, output format, and parameter semantics adequately. However, without annotations, it lacks details on behavioral traits like safety or performance, which slightly reduces completeness for an agent's full understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful semantics for the single parameter 'course_id' by explaining it's 'The Gradescope course ID (found via list_courses),' which clarifies its source and context. Since there's only one parameter and schema description coverage is 0%, this compensation is effective, though it doesn't detail format or constraints beyond the schema's basic type.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get all assignments for a specific Gradescope course.' It specifies the verb ('Get') and resource ('assignments'), and distinguishes it from siblings like 'tool_get_assignment_details' by indicating it retrieves all assignments rather than details of a single one. However, it doesn't explicitly contrast with all relevant siblings (e.g., 'tool_get_assignment_submissions'), so it's not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implied usage guidance by mentioning that 'course_id' is 'found via list_courses,' which suggests using 'tool_list_courses' first. It doesn't explicitly state when to use this tool versus alternatives like 'tool_get_assignment_details' or 'tool_get_assignment_submissions,' nor does it provide exclusions or detailed context, so it's adequate but lacks explicit guidelines.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_assignment_statisticsA

Get comprehensive statistics for an assignment.

Returns assignment-level summary (mean, median, min/max, std dev) and
per-question breakdowns. Highlights low-scoring questions.
Requires instructor/TA access.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context such as the return format ('assignment-level summary... per-question breakdowns'), highlights specific outputs ('low-scoring questions'), and mentions access requirements. However, it lacks details on rate limits, error handling, or data freshness, which are important for a statistical tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose and key outputs, followed by access requirements and parameter explanations. Every sentence adds value, with no redundant information. Minor improvements could include bullet points for clarity, but overall it's efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, no annotations, and the presence of an output schema (which handles return values), the description is largely complete. It covers purpose, outputs, access needs, and parameter context. However, it could benefit from more behavioral details like performance characteristics or usage limits to fully guide the agent in all scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'course_id' and 'assignment_id' refer to 'Gradescope course ID' and 'assignment ID', respectively, providing context that the schema's generic titles ('Course Id', 'Assignment Id') do not. This compensates well for the low schema coverage, though it doesn't detail format constraints like ID structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('Get comprehensive statistics') and resources ('assignment'), and distinguishes it from siblings like 'tool_get_assignment_details' by focusing on statistical analysis rather than general information. However, it doesn't explicitly contrast with all similar siblings like 'tool_export_assignment_scores', which slightly limits differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implied usage context by stating 'Requires instructor/TA access', indicating when authorization is needed. It doesn't explicitly state when to use this tool versus alternatives like 'tool_export_assignment_scores' or 'tool_get_assignment_details', nor does it mention exclusions or prerequisites beyond access, leaving some ambiguity for the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_assignment_submissionsA

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.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: access restrictions ('instructor/TA only'), performance characteristics ('May be slow for large classes'), and return format ('Returns a list of submission IDs and file counts'). This covers important operational context beyond basic functionality.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: purpose statement first, return format second, performance note third, and parameter explanations last. Every sentence adds value with zero waste, making it easy to scan and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters, no annotations, and an output schema (which handles return values), the description is reasonably complete. It covers purpose, access, performance, and parameters. It could mention pagination or error cases, but for a read-only tool with output schema, it's mostly adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It documents both parameters (course_id, assignment_id) with brief explanations, adding meaning beyond the schema's titles. However, it doesn't provide format details, examples, or constraints, so it only partially compensates for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get all submissions for an assignment' with the specific resource (submissions) and verb (get). It distinguishes from siblings like 'tool_get_student_submission' (singular) and 'tool_get_assignment_details' (metadata). However, it doesn't explicitly contrast with all relevant siblings, keeping it at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: 'instructor/TA only' specifies the required role, and 'May be slow for large classes' warns about performance limitations. It doesn't explicitly state when NOT to use it or name alternatives (e.g., 'tool_get_student_submission' for individual submissions), so it's not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_course_rosterA

Get the full roster (students, TAs, instructors) for a course.

Returns a table grouped by role with name, email, SID, and submission count.
Requires instructor or TA access to the course.

Args:
    course_id: The Gradescope course ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the return format ('table grouped by role with name, email, SID, and submission count') and access requirements ('instructor or TA access'), covering key behavioral aspects. It doesn't mention rate limits or pagination, but provides sufficient context for safe use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with three sentences: purpose, return format, access requirements, and parameter explanation. Each sentence adds essential information without redundancy, making it easy to scan and understand.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (single parameter, read-only operation), no annotations, and the presence of an output schema (which handles return value details), the description is complete. It covers purpose, access control, return format, and parameter semantics, leaving no significant gaps for the agent to operate effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It adds meaning by explaining that 'course_id' is 'The Gradescope course ID', clarifying the parameter's purpose beyond the schema's generic title 'Course Id'. This adequately covers the single parameter's semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get'), resource ('full roster for a course'), and scope ('students, TAs, instructors'), distinguishing it from sibling tools like tool_get_assignment_submissions or tool_get_student_submission that focus on submissions rather than roster data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It specifies when to use this tool by stating 'Requires instructor or TA access to the course', providing clear context about prerequisites. However, it doesn't explicitly mention when not to use it or name alternatives among siblings, such as tool_get_assignment_graders which might overlap in some contexts.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_extensionsA

Get all student extensions for a specific assignment.

Returns a table of extensions with user ID, name, and modified dates.
Requires instructor or TA access.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses access requirements ('Requires instructor or TA access') and return format ('Returns a table of extensions with user ID, name, and modified dates'), which adds useful behavioral context. However, it lacks details on rate limits, error handling, or pagination, leaving gaps for a read operation with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the purpose, followed by return details and access requirements, with parameter explanations in a clear 'Args' section. Every sentence adds value without redundancy, making it efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no annotations, but with an output schema), the description is mostly complete. It covers purpose, access requirements, parameters, and return format. Since an output schema exists, it need not explain return values in detail, but it could benefit from mentioning sibling tool relationships or error cases for full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, but the description compensates by listing and briefly explaining both parameters ('course_id: The Gradescope course ID' and 'assignment_id: The assignment ID'). This adds meaning beyond the bare schema. However, it does not provide format examples, constraints, or links to other tools, so it meets the baseline for partial compensation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get all student extensions for a specific assignment.' It specifies the verb ('Get'), resource ('student extensions'), and scope ('for a specific assignment'), making it easy to understand. However, it does not explicitly differentiate from sibling tools like 'tool_set_extension' or 'tool_modify_assignment_dates', which prevents a score of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for usage: 'Requires instructor or TA access.' This indicates prerequisites and when the tool is applicable. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'tool_set_extension' for modifying extensions or 'tool_get_assignment_details' for general assignment info), so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_grading_progressA

Get the grading progress dashboard for an assignment.

Shows each question's grading status: how many submissions have been graded,
assigned graders, and completion percentage. Requires instructor/TA access.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by stating access requirements ('Requires instructor/TA access') and describing what the dashboard shows. However, it doesn't mention potential limitations like rate limits, whether the data is real-time or cached, error conditions, or response format details. For a tool with no annotations, this leaves some behavioral aspects unclear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly structured and concise: a clear purpose statement, followed by what the dashboard shows, then access requirements, and finally parameter explanations. Every sentence adds value with zero wasted words. It's front-loaded with the core functionality and efficiently covers necessary details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (which handles return values), no annotations, and simple parameters, the description is reasonably complete. It covers purpose, usage context, access requirements, and parameter basics. The main gap is lack of behavioral details like rate limits or error handling, but the output schema reduces the need to describe return format. For a read-only progress dashboard tool, this is fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter documentation. The description compensates by listing both parameters (course_id and assignment_id) and explaining they are Gradescope IDs. However, it doesn't provide format examples, validation rules, or where to find these IDs. Given the 0% schema coverage, the description adds meaningful but incomplete parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get the grading progress dashboard for an assignment' with specific details about what it shows (grading status, submissions graded, assigned graders, completion percentage). It distinguishes from siblings like tool_get_assignment_statistics or tool_get_assignment_submissions by focusing on grading progress rather than general statistics or raw submissions. However, it doesn't explicitly name alternatives, keeping it at 4 instead of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: when needing grading progress information for an assignment. It specifies access requirements ('Requires instructor/TA access'), which helps determine appropriateness. It doesn't explicitly state when not to use it or name specific alternatives among the many sibling tools, but the context is sufficiently clear for effective usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_next_ungradedA

Navigate to the next ungraded submission.

Returns the full grading context for the next ungraded submission,
or a message that all submissions are graded.

Args:
    course_id: The current course ID.
    question_id: The current question ID.
    submission_id: The current Question Submission ID (optional).
        If omitted or invalid (e.g. a Global Submission ID), the tool
        will auto-discover a valid submission to navigate from.
    output_format: "markdown" (default) or "json".

ParametersJSON Schema

Name	Required	Default
`course_id`	Yes
`question_id`	Yes
`submission_id`	No
`output_format`	No	markdown

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses key behaviors: it returns grading context or a completion message, handles optional submission_id with auto-discovery, and supports output formats. However, it lacks details on permissions, rate limits, or side effects (e.g., whether navigation affects state). It adds useful context but is incomplete for a tool with mutation-like navigation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by return behavior and parameter details in a structured format. Every sentence adds value—no fluff or repetition—making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (navigation with auto-discovery), no annotations, and an output schema (which handles return values), the description is largely complete. It covers purpose, usage, parameters, and output behavior. However, it lacks some behavioral context like error handling or prerequisites, leaving minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains all four parameters: course_id and question_id as required IDs, submission_id as optional with auto-discovery behavior, and output_format with default and options. This adds significant meaning beyond the bare schema, though it could detail ID formats or validation rules.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Navigate to the next ungraded submission') and resource (grading context), distinguishing it from siblings like tool_get_submission_grading_context (which gets context for a specific submission) or tool_get_grading_progress (which tracks overall progress). It precisely defines the verb and scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (grading workflow) and mentions an alternative outcome ('all submissions are graded'), but does not explicitly state when to use this tool versus alternatives like tool_get_submission_grading_context (for a known submission) or tool_get_grading_progress (for progress overview). It provides clear context but lacks explicit sibling differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_question_rubricA

Get rubric items for a question without needing a submission ID.

Auto-discovers a submission to extract rubric data. Use when you know
the question_id from outline but don't have a submission ID yet.

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID from outline.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`question_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the key behavioral trait: 'Auto-discovers a submission to extract rubric data,' which explains how it works without a submission ID. However, it doesn't cover other important aspects like authentication requirements, rate limits, error conditions, or what happens if no submission is found. The description adds some value but leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise and well-structured. It starts with the core purpose, explains the auto-discovery mechanism, provides usage guidance, and lists parameter meanings—all in four brief sentences with zero wasted words. Every sentence earns its place by adding essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no annotations, but with an output schema), the description is reasonably complete. It covers the purpose, usage context, and parameter meanings. The presence of an output schema means the description doesn't need to explain return values. However, it lacks details on behavioral aspects like error handling or permissions, which would be helpful for full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter documentation. The description adds basic semantics: 'course_id: The Gradescope course ID' and 'question_id: The question ID from outline.' This clarifies what the parameters represent, but it doesn't provide format details, constraints, or examples. Since there are only 2 parameters, this minimal explanation is adequate for a baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get rubric items for a question' with the specific constraint 'without needing a submission ID.' It distinguishes itself from sibling tools like 'tool_get_submission_grading_context' or 'tool_get_student_submission' that likely require submission IDs. However, it doesn't explicitly name these alternatives, preventing a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool: 'Use when you know the question_id from outline but don't have a submission ID yet.' It clearly defines the prerequisite context (having a question_id but lacking a submission ID). It doesn't specify when NOT to use it or name alternative tools, which keeps it from a score of 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_regrade_detailA

Get detailed information about a specific regrade request.

Shows the student's regrade message, the current rubric, applied rubric items,
the grader's response (if any), and submission page links. Use question_id and
submission_id from the regrade request listing.
Requires instructor/TA access.

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID (from get_regrade_requests).
    submission_id: The submission ID (from get_regrade_requests).

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`question_id`	Yes
`submission_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully adds important context beyond what's in the schema: it specifies the tool 'Requires instructor/TA access' (permissions requirement), describes what information is returned (student message, rubric details, grader response, links), and indicates parameter sources (from get_regrade_requests). It doesn't mention rate limits, pagination, or error behavior, but provides substantial operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with zero waste: a clear purpose statement, specific information returned, usage guidance with parameter sources, and access requirements. Every sentence adds value, and it's appropriately sized for a tool with 3 parameters and no annotations. The information is front-loaded with the core purpose first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (regrade detail retrieval with 3 parameters), no annotations, but with an output schema present, the description provides substantial context. It covers purpose, returned information, parameter semantics, and access requirements. The output schema existence means the description doesn't need to explain return values. It could potentially mention error cases or rate limits, but covers the essential operational context well.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate for the schema's lack of parameter documentation. It successfully adds meaning for all three parameters: course_id is identified as 'The Gradescope course ID', and both question_id and submission_id are specified as coming 'from get_regrade_requests'. This provides crucial context about parameter sources and relationships that isn't in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get detailed information') and resource ('about a specific regrade request'), and distinguishes it from siblings by specifying it's for detailed regrade info rather than listing regrade requests (tool_get_regrade_requests) or other operations. It explicitly lists the specific information returned: student's regrade message, current rubric, applied rubric items, grader's response, and submission page links.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: when you need detailed information about a specific regrade request, and it specifies that question_id and submission_id should come 'from the regrade request listing' (presumably tool_get_regrade_requests). However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_regrade_requestsA

List all regrade requests for an assignment.

Returns a table of pending and completed regrade requests with student name,
question, grader, status, and identifiers for fetching details.
Requires instructor/TA access.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context: it mentions the return format ('table of pending and completed regrade requests') and access requirements ('Requires instructor/TA access'). However, it lacks details on potential side effects, rate limits, or error handling, leaving some behavioral aspects unclear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by return details and access requirements, then parameter explanations. Every sentence earns its place with no wasted words, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no annotations, but with an output schema), the description is largely complete. It covers purpose, return format, access requirements, and parameters. Since an output schema exists, it needn't explain return values in detail, but it could benefit from mentioning any limitations (e.g., pagination) to achieve full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It explicitly lists and describes both parameters ('course_id: The Gradescope course ID' and 'assignment_id: The assignment ID'), adding clear meaning beyond the bare schema. This fully compensates for the lack of schema descriptions, though it doesn't provide examples or format specifics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('List all regrade requests') and resource ('for an assignment'), distinguishing it from siblings like tool_get_regrade_detail (which fetches details for a specific request) and tool_get_assignment_submissions (which focuses on submissions rather than regrade requests). The verb 'List' is precise and the scope 'all regrade requests' is well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by specifying 'Requires instructor/TA access,' which indicates when to use this tool based on user permissions. However, it does not explicitly state when not to use it or name alternatives (e.g., tool_get_regrade_detail for fetching details of a specific request), which prevents a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_student_submissionA

Get a specific student's most recent submission (instructor/TA only).

Returns links to the submission files.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.
    student_email: The student's email address.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes
`student_email`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions that it returns links to submission files, which is helpful behavioral information. However, it doesn't disclose important traits like whether this is a read-only operation, potential rate limits, authentication requirements beyond the role hint, or what happens if no submission exists. For a tool with zero annotation coverage, this leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear purpose statement, role restriction, return value information, and parameter explanations in a bullet-like format. Every sentence earns its place with no wasted words, and the most important information (what the tool does) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there's an output schema (which handles return value documentation), the description doesn't need to explain return values in detail. However, for a tool with 3 parameters, 0% schema coverage, and no annotations, the description should provide more behavioral context about error conditions, permissions, and operational constraints to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides clear semantic meaning for all three parameters (course_id, assignment_id, student_email), explaining what each represents. This adds substantial value beyond the bare schema, though it doesn't specify format details like email validation or ID patterns.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get a specific student's most recent submission'), identifies the resource (submission files), and distinguishes it from siblings like tool_get_assignment_submissions (which likely returns all submissions) by specifying it's for a single student's most recent submission. The instructor/TA restriction further clarifies the access context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states 'instructor/TA only', providing clear context about when to use this tool based on user role. However, it doesn't mention when to use alternatives like tool_get_assignment_submissions or tool_smart_read_submission, nor does it specify prerequisites beyond the parameters.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_get_submission_grading_contextA

Get full grading context for a question submission.

Returns current rubric items (with IDs), applied evaluations, score,
comments, point adjustment, navigation URLs (next/prev/ungraded),
and submission page images. Use this before applying grades.

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID.
    submission_id: The question submission ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`question_id`	Yes
`submission_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It describes the return data comprehensively (rubric items, evaluations, score, comments, navigation URLs, images) and implies a read-only operation, but does not disclose behavioral traits like authentication needs, rate limits, or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the purpose, followed by a detailed list of returns, and ends with usage guidance and parameter explanations. Every sentence adds value with zero waste, making it efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (grading context tool), no annotations, and an output schema exists, the description is mostly complete. It details what the tool returns and when to use it, but lacks information on permissions, errors, or pagination that could enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It lists all three parameters (course_id, question_id, submission_id) and clarifies they are IDs for Gradescope entities, adding meaning beyond the bare schema. However, it does not provide format examples or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and resource 'full grading context for a question submission', specifying it returns rubric items, evaluations, score, comments, navigation URLs, and images. It distinguishes from siblings like tool_apply_grade (which applies grades) and tool_get_question_rubric (which focuses only on rubric).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by stating 'Use this before applying grades', which implicitly guides when to use it relative to tool_apply_grade. However, it does not explicitly mention when not to use it or name alternative tools for similar purposes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_grade_answer_groupA

Batch-grade ALL submissions in an answer group at once.

**WARNING**: This grades N students at once. Use with caution.

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID.
    group_id: The answer group ID.
    rubric_item_ids: Rubric item IDs to apply.
    point_adjustment: Point adjustment.
    comment: Grader comment.
    confirm_write: Must be True to apply grades.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`question_id`	Yes
`group_id`	Yes
`rubric_item_ids`	No
`point_adjustment`	No
`comment`	No
`confirm_write`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it's a batch operation affecting multiple students, includes a safety warning, and specifies a confirm_write parameter as a safeguard. It doesn't detail permissions, rate limits, or exact effects on grades, but covers essential mutation context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and warning, followed by a structured Args section. Every sentence earns its place: the first states the action, the second warns, and the parameter list is necessary given low schema coverage. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a complex mutation tool with 7 parameters, 0% schema coverage, no annotations, but an output schema exists, the description is mostly complete. It covers purpose, caution, and parameter meanings, but could benefit from more on prerequisites or error handling. The output schema reduces need for return value details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It lists all 7 parameters with brief explanations (e.g., 'Rubric item IDs to apply,' 'Point adjustment,' 'Grader comment'), adding meaningful semantics beyond the schema's titles. However, it lacks details on formats or constraints for IDs and adjustments.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('batch-grade ALL submissions'), the target resource ('answer group'), and scope ('at once'). It distinguishes from sibling tools like tool_apply_grade (which likely grades individual submissions) by emphasizing the batch nature and N students scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context with the 'WARNING' about grading N students at once and 'Use with caution,' which implicitly guides when to use this tool versus individual grading alternatives. However, it doesn't explicitly name alternative tools or state when-not-to-use scenarios beyond the caution.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_list_coursesA

List all Gradescope courses for the authenticated user.

Returns courses grouped by role (instructor vs student), including course ID, name, semester, and assignment count.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format (grouped by role, with specific fields) and implies a read-only operation, but lacks details on permissions, rate limits, or error handling. It adds some context but is not comprehensive for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by essential return details in the second. Both sentences add value without redundancy, making it efficient and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, output schema exists), the description is largely complete, covering purpose and return data. However, with no annotations, it could benefit from more behavioral context (e.g., authentication requirements or limitations) to fully compensate for the lack of structured metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately omits parameter details, focusing on the tool's purpose and output, which aligns with the schema's completeness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('List all Gradescope courses') and resource ('for the authenticated user'), distinguishing it from sibling tools that focus on assignments, rubrics, submissions, or grading. It precisely defines the tool's scope without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying 'for the authenticated user' and listing return data (courses grouped by role, with details like ID and assignment count), which helps differentiate it from tools like tool_get_course_roster. However, it does not explicitly state when not to use it or name alternatives, leaving some guidance implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_modify_assignment_datesA

Modify the dates of an assignment (release, due, late due).

At least one date must be provided. Only the provided dates will be changed.
Requires instructor or TA access.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.
    release_date: New release date (ISO format: YYYY-MM-DDTHH:MM), or None to keep unchanged.
    due_date: New due date (ISO format: YYYY-MM-DDTHH:MM), or None to keep unchanged.
    late_due_date: New late due date (ISO format: YYYY-MM-DDTHH:MM), or None to keep unchanged.
    confirm_write: Must be True to apply the date change.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes
`release_date`	No
`due_date`	No
`late_due_date`	No
`confirm_write`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it's a mutation operation (implied by 'Modify'), requires specific permissions ('instructor or TA access'), has a safety mechanism ('confirm_write: Must be True'), and explains update behavior ('Only the provided dates will be changed'). It doesn't mention rate limits or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly structured and front-loaded: the first sentence states the purpose, followed by constraints, permissions, then detailed parameter explanations. Every sentence earns its place with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with 6 parameters, no annotations, but with an output schema, the description is quite complete. It covers purpose, constraints, permissions, and all parameters thoroughly. The output schema presumably handles return values, so the description doesn't need to explain them. It could mention potential side effects more explicitly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, but the description fully compensates by explaining all 6 parameters in detail: their purpose, format requirements ('ISO format: YYYY-MM-DDTHH:MM'), null behavior ('or None to keep unchanged'), and constraints ('At least one date must be provided'). This adds substantial value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Modify the dates of an assignment') and identifies the exact resources affected ('release, due, late due'), distinguishing it from siblings like 'tool_rename_assignment' or 'tool_set_extension' which handle different aspects of assignments.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use it ('Modify the dates of an assignment') and prerequisites ('Requires instructor or TA access'), but doesn't explicitly state when not to use it or name alternative tools for related date operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_prepare_answer_keyA

Prepare a complete answer key for an entire assignment.

Extracts ALL questions from the outline (prompt text, reference answers,
explanations) and saves to /tmp/gradescope-answerkey-{assignment_id}.md.
Run this ONCE before grading to avoid re-fetching question details.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly describes the tool's action (extracts questions, saves to a specific file path), purpose (to avoid re-fetching), and output location (/tmp/gradescope-answerkey-{assignment_id}.md). However, it doesn't mention potential side effects like file overwriting or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with three sentences: purpose statement, detailed action, and usage timing. Every sentence adds value without redundancy. The parameter documentation is clear and directly relevant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (which handles return values), no annotations, and only 2 parameters with 0% schema coverage, the description does well by explaining the tool's purpose, behavior, and parameter roles. However, it lacks details on error handling or what happens if the file already exists, which would be helpful for a tool that saves files.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaningful context for both parameters: course_id is described as 'The Gradescope course ID' and assignment_id as 'The assignment ID', which clarifies their roles in locating the specific assignment. However, it doesn't provide format examples or validation rules.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Prepare a complete answer key'), the resource ('entire assignment'), and the scope ('extracts ALL questions from the outline'). It distinguishes itself from siblings like tool_get_assignment_outline (which likely fetches but doesn't process) and tool_grade_answer_group (which grades specific answers rather than preparing a key).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool ('Run this ONCE before grading to avoid re-fetching question details') and provides a clear timing guideline. It implies this is a preparatory step distinct from actual grading tools like tool_grade_answer_group, though it doesn't name specific alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_prepare_grading_artifactB

Prepare a cached /tmp markdown artifact for grading a question.

The artifact includes the prompt, rubric, reference-answer notes, page URLs,
crop regions, and a confidence gate for auto-grading.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.
    question_id: The question ID to prepare.
    submission_id: Optional sample submission ID to use for rubric/page context.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes
`question_id`	Yes
`submission_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions the artifact is cached in /tmp and includes specific components, but doesn't disclose behavioral traits like whether this is a read-only operation, if it requires specific permissions, potential rate limits, or what happens on failure. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the main purpose and listing included components. The Args section is clear and necessary given low schema coverage. There's minimal waste, though it could be slightly more streamlined by integrating the parameter explanations into the main text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, 0% schema coverage, and an output schema present (which reduces need to explain return values), the description is moderately complete. It covers the tool's purpose and parameters but lacks details on behavioral aspects like error handling or performance. For a tool with 4 parameters and no annotations, it should provide more context on usage constraints or outcomes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning by explaining each parameter's purpose: course_id, assignment_id, and question_id are required for identification, while submission_id is optional for providing rubric/page context. This clarifies semantics beyond the schema's basic titles, though it doesn't detail formats or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('prepare') and the resource ('cached /tmp markdown artifact for grading a question'), specifying it includes prompt, rubric, reference-answer notes, page URLs, crop regions, and confidence gate. It distinguishes from siblings like tool_grade_answer_group or tool_get_question_rubric by focusing on artifact preparation rather than grading or rubric retrieval, though it doesn't explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when preparing grading artifacts, such as for auto-grading with a confidence gate, but doesn't explicitly state when to use this tool versus alternatives like tool_prepare_answer_key or tool_get_submission_grading_context. It mentions optional submission_id for rubric/page context, suggesting context for when to include it, but lacks clear exclusions or named sibling comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_rename_assignmentA

Rename an assignment on Gradescope.

Requires instructor or TA access.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.
    new_title: The new title for the assignment.
    confirm_write: Must be True to perform the rename.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes
`new_title`	Yes
`confirm_write`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the access requirement and includes a 'confirm_write' parameter as a safety measure, which adds useful context. However, it lacks details on potential side effects (e.g., if renaming affects linked data), rate limits, or error conditions, leaving gaps for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by access requirements and parameter details in a clear, bullet-like structure. Every sentence earns its place with no wasted words, making it highly efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that this is a mutation tool with no annotations but an output schema exists, the description covers the essential purpose, access needs, and parameters adequately. However, it could benefit from more behavioral context (e.g., confirmation of success/failure outcomes) to fully compensate for the lack of annotations, though the output schema mitigates some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It lists all four parameters with brief explanations (e.g., 'The new title for the assignment'), adding meaningful semantics beyond the schema's titles. However, it does not provide format details (e.g., ID formats or title constraints), slightly limiting its utility.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Rename an assignment') and the platform ('on Gradescope'), distinguishing it from sibling tools like 'tool_modify_assignment_dates' or 'tool_get_assignment_details'. It uses a precise verb ('rename') and identifies the resource ('assignment').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states 'Requires instructor or TA access,' providing clear context for when to use this tool based on user permissions. However, it does not specify when not to use it or mention alternatives (e.g., compared to 'tool_modify_assignment_dates'), which prevents a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_set_extensionA

Add or update an extension for a student on an assignment.

If the student already has an extension, it will be overwritten.
At least one date must be provided. Dates must be in order:
release_date <= due_date <= late_due_date.

Requires instructor or TA access.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.
    user_id: The student's Gradescope user ID (found via get_course_roster).
    release_date: Extension release date (ISO format: YYYY-MM-DDTHH:MM).
    due_date: Extension due date (ISO format: YYYY-MM-DDTHH:MM).
    late_due_date: Extension late due date (ISO format: YYYY-MM-DDTHH:MM).
    confirm_write: Must be True to apply the extension update.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes
`user_id`	Yes
`release_date`	No
`due_date`	No
`late_due_date`	No
`confirm_write`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the overwrite behavior ('If the student already has an extension, it will be overwritten'), permission requirements ('Requires instructor or TA access'), and the confirmation mechanism ('confirm_write: Must be True to apply the extension update'). It doesn't mention error conditions, rate limits, or what the output contains, but provides substantial operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with purpose first, then behavioral notes, then detailed parameter explanations. Every sentence earns its place: the first states the core function, the next three describe critical behaviors, and the parameter section provides essential context. There's no redundant or verbose content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with 7 parameters, 0% schema coverage, no annotations, but with an output schema present, the description is quite complete. It covers purpose, behavior, permissions, parameter semantics, and constraints. The presence of an output schema means return values don't need explanation. Minor gaps include lack of error case descriptions and no explicit distinction from sibling tools like 'tool_modify_assignment_dates'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining all 7 parameters. It clarifies the purpose of each parameter, provides format requirements ('ISO format: YYYY-MM-DDTHH:MM'), ordering constraints ('Dates must be in order: release_date <= due_date <= late_due_date'), and special requirements ('At least one date must be provided', 'confirm_write: Must be True'). This adds significant value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Add or update an extension for a student on an assignment') and identifies the resources involved (student, assignment, extension). It distinguishes itself from sibling tools like 'tool_get_extensions' (which reads extensions) and 'tool_modify_assignment_dates' (which modifies assignment-level dates rather than student-specific extensions).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: when managing student-specific assignment extensions. It mentions prerequisites ('Requires instructor or TA access') and references a related tool ('user_id... found via get_course_roster'). However, it doesn't explicitly state when NOT to use it (e.g., vs. modifying assignment-level dates with 'tool_modify_assignment_dates') or provide alternatives for related operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_smart_read_submissionA

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.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes
`question_id`	Yes
`submission_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it returns a structured reading plan with prioritized tiers (crop region, full page, adjacent pages), a confidence score, and a recommended action. However, it lacks details on permissions, rate limits, error handling, or whether it's read-only or mutative, leaving gaps for an AI agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by a bulleted list detailing the output structure, and ends with parameter explanations. Every sentence adds value without redundancy, making it efficient and well-structured for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (involving tiered analysis), no annotations, and an output schema (which covers return values), the description is mostly complete. It explains the purpose, output format, and parameters well. However, it could improve by addressing behavioral aspects like permissions or error cases, slightly reducing completeness for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It explicitly lists all four parameters (course_id, assignment_id, question_id, submission_id) and clarifies they are IDs for Gradescope entities, adding crucial meaning beyond the schema's generic titles like 'Course Id'. This fully addresses the parameter semantics gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('get a smart, tiered reading plan') and identifies the resource ('student's submission'). It distinguishes itself from siblings by focusing on reading plan generation rather than grading, assessment, or data retrieval functions like tool_get_student_submission or tool_assess_submission_readiness.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context through the parameters (course_id, assignment_id, etc.), suggesting it's for analyzing specific submissions within Gradescope. However, it doesn't explicitly state when to use this tool versus alternatives like tool_get_student_submission or tool_assess_submission_readiness, nor does it mention prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_update_rubric_itemA

Update an existing rubric item's description or weight.

**WARNING**: Changes cascade to ALL submissions with this item applied.

Args:
    course_id: The Gradescope course ID.
    question_id: The question ID.
    rubric_item_id: The rubric item ID to update.
    description: New description, or None to keep unchanged.
    weight: New point value, or None to keep unchanged.
    confirm_write: Must be True to apply the update.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`question_id`	Yes
`rubric_item_id`	Yes
`description`	No
`weight`	No
`confirm_write`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and excels by disclosing key behavioral traits: it's a mutation tool (implied by 'Update'), includes a critical warning about cascading changes to all submissions, specifies that description/weight can be kept unchanged with None, and requires explicit confirmation via confirm_write. This covers safety, side-effects, and user intent verification.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and critical warning, followed by a concise parameter breakdown. Every sentence earns its place: the first states the action, the second warns of cascading effects, and the Args section efficiently documents each parameter without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (mutation with cascading effects), no annotations, and an output schema (which handles return values), the description is complete. It covers purpose, critical behavior, all parameters, and usage context, leaving no gaps for the agent to operate safely and effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate—and it does fully. It explains all 6 parameters: course_id, question_id, and rubric_item_id as identifiers, and clarifies that description and weight accept new values or None to keep unchanged, with confirm_write required to apply updates. This adds essential meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Update an existing rubric item's description or weight'), identifies the resource ('rubric item'), and distinguishes from siblings like tool_create_rubric_item and tool_delete_rubric_item by focusing on modification rather than creation or deletion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (updating rubric items) and includes a critical warning about cascading effects, but it doesn't explicitly mention when not to use it or name specific alternatives among the sibling tools (e.g., tool_create_rubric_item for new items).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tool_upload_submissionC

Upload files as a submission to a Gradescope assignment.

Args:
    course_id: The Gradescope course ID.
    assignment_id: The assignment ID.
    file_paths: List of absolute file paths to upload.
    leaderboard_name: Optional leaderboard display name.
    confirm_write: Must be True to perform the upload.

ParametersJSON Schema

Name	Required	Description	Default
`course_id`	Yes
`assignment_id`	Yes
`file_paths`	Yes
`leaderboard_name`	No
`confirm_write`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but offers minimal behavioral insight. It implies a write operation ('Upload') and includes a 'confirm_write' parameter as a safety measure, but doesn't disclose permissions needed, rate limits, whether uploads are reversible, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is inadequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear purpose statement followed by a bullet-point-like parameter list. Every sentence serves a purpose, though the parameter explanations could be more detailed. It's appropriately sized for a 5-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (write operation, 5 parameters, no annotations) and the presence of an output schema (which reduces need to describe returns), the description is minimally adequate. It covers the core action and parameters but lacks behavioral context, usage guidelines, and detailed parameter semantics, leaving gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter documentation. The description adds basic semantics by listing parameters with brief explanations (e.g., 'List of absolute file paths to upload'), but doesn't elaborate on formats (e.g., what constitutes a valid course_id) or constraints (e.g., file size limits). It compensates partially but not fully for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Upload files') and target ('as a submission to a Gradescope assignment'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'tool_get_assignment_submissions' or 'tool_get_student_submission', which are read operations versus this write operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing course/assignment access), exclusions, or comparisons to sibling tools like 'tool_assess_submission_readiness' or 'tool_export_assignment_scores'. The agent must infer usage from the purpose alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

33 tool updatesv0.1.0Mar 18, 2026
- First observedtool_apply_grade
- First observedtool_assess_submission_readiness
- First observedtool_cache_relevant_pages
- First observedtool_create_rubric_item
- First observedtool_delete_rubric_item
- First observedtool_export_assignment_scores
- First observedtool_get_answer_group_detail
- First observedtool_get_answer_groups
- First observedtool_get_assignment_details
- First observedtool_get_assignment_graders
- First observedtool_get_assignment_outline
- First observedtool_get_assignment_statistics
- First observedtool_get_assignment_submissions
- First observedtool_get_assignments
- First observedtool_get_course_roster
- First observedtool_get_extensions
- First observedtool_get_grading_progress
- First observedtool_get_next_ungraded
- First observedtool_get_question_rubric
- First observedtool_get_regrade_detail
- First observedtool_get_regrade_requests
- First observedtool_get_student_submission
- First observedtool_get_submission_grading_context
- First observedtool_grade_answer_group
- First observedtool_list_courses
- First observedtool_modify_assignment_dates
- First observedtool_prepare_answer_key
- First observedtool_prepare_grading_artifact
- First observedtool_rename_assignment
- First observedtool_set_extension
- First observedtool_smart_read_submission
- First observedtool_update_rubric_item
- First observedtool_upload_submission

Deploy Server

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.7/5.0

Scored 2026-04-13 12:15 across 33 tools

Disambiguation4/5

Most tools have distinct purposes targeting specific resources and actions, such as grading, rubric management, or data retrieval. However, some overlap exists between tools like tool_assess_submission_readiness and tool_smart_read_submission, which both assess submissions for grading readiness, potentially causing confusion in tool selection.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case, such as tool_apply_grade, tool_get_assignment_details, and tool_update_rubric_item. This predictability makes it easy for agents to understand and navigate the toolset without naming conflicts.

Tool Count2/5

With 33 tools, the count is excessive for a grading-focused server, leading to potential overwhelm and inefficiency. A more streamlined set of 10-20 tools could cover the same domain without redundancy, such as merging similar assessment or retrieval tools.

Completeness5/5

The toolset provides comprehensive coverage of the Gradescope domain, including CRUD operations for grades, rubrics, assignments, and submissions, along with advanced features like answer groups, regrades, and statistics. No significant gaps are apparent for grading workflows.

Maintenance

ActivityMaintained

ResponsivenessSlow

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

OneSchema MCP Server
co.oneschema
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Data Platforms App Automation
1
ZapierOAuth
com.zapier
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
App Automation Workplace & Productivity
2297
driflyte-mcp-server
com.driflyte
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Search Web Scraping Knowledge & Memory
211
ClawLinkOAuth
dev.claw-link
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
App Automation Workplace & Productivity
24

Related MCP Servers

Google Classroom MCP Server
Education & Learning Tools Search
faizan45640
A
license
Not graded
quality
D
maintenance
An MCP server that enables AI assistants to access and interact with Google Classroom data, allowing users to view courses, course details, and assignments through natural language commands.
Updated a year ago (2025-07-28 14:58 UTC)
389 npm
6
MIT
Moodle MCP Server
Education & Learning Tools Developer Tools
cfsandoval
A
license
B
quality
D
maintenance
An MCP server that enables LLMs to interact with the Moodle platform to manage courses, students, assignments, and quizzes.
Updated a year ago (2025-08-01 18:05 UTC)
7
8 npm
MIT
Canvas LMS MCP Server
Education & Learning Tools Content Management Systems
bruchris
A
license
B
quality
A
maintenance
MCP server for Canvas LMS, providing 115+ tools to read courses, assignments, submissions, rubrics, quizzes; grade, comment, manage course content, and handle Canvas admin workflows from any AI agent.
Updated a day ago (2026-10-22 10:37 UTC)
182
1,354 npm
10
MIT
Canvas Agent
Education & Learning Tools Project Management Communication
hughsibbele
A
license
A
quality
B
maintenance
MCP server that connects AI assistants to Instructure Canvas LMS, enabling teachers and administrators to manage courses, assignments, grades, and more through natural language.
Updated 2 months ago (2026-08-18 15:29 UTC)
80
18 npm
1
MIT