List Submissions Awaiting Grading

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

The annotations already indicate a safe read-only operation, but the description adds rich behavioral context: exactly what gets surfaced, what does not (New Quizzes pending_review, fill-in-the-blank), the submission-level-only limitation, pseudonymization behavior, and the version-specific caveat. There is no contradiction with the annotations; everything aligns with readOnlyHint=true.

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

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

The description is well-structured and front-loaded with the core outcome, then moved into return-shape, parameters, and known limitations, which makes it easy to navigate. It is longer than the strict minimum because the Parameters section duplicates schema content, but the known-limitations list adds enough standalone value to justify most of its length.

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

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

With no output schema, the description still fully explains the return shape (triage list grouped by assignment or quiz, with student identity, workflow state, submitted_at, and pending manual-grading flag), sorting, filter scenario categories, and edge cases such as New Quizzes, fill-in-the-blank, and pseudonymized students. This is a very complete specification for an ungrading-queue viewer.

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

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

The schema already has 100% description coverage, so the parameter meaning is available without relying on the tool description. The description adds the Parameters section, but it mostly restates the schema semantics for combine, assignment_ids, include_quizzes, include_assignments, and only_pending_review. Therefore it stays at the baseline: no harm, but no significant additional parameter knowledge.

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

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

The description opens with a specific verb-plus-resource statement: 'Lists all submissions in a course that still need a human grade, sorted oldest-waiting first.' It clearly distinguishes this from generic list tools by enumerating the two workflow states, submitted and pending_review, and explains the triage grouping.

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

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

The description conveys clear usage context for grading triage and explicitly tells the agent when not to rely on it (e.g., New Quizzes may not show pending_review here; use SpeedGrader or the New Quizzes interface). It also directs the agent to resolve_pseudonym for pseudonymized student identities. It does not explicitly name sibling MCP tools such as list_submissions as alternatives for general submission listing, which keeps it from a 5.

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