Get Quiz Submission Events

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is known. The description adds valuable behavioral context by disclosing that Canvas enforces access permissions (instructors and submitting student only), which is beyond the annotations. It also clarifies the ordering guarantee ('in chronological order') and the limitation for New Quizzes. The only minor gap is not describing the exact response shape, but with no output schema that is a lesser concern.

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 a compact paragraph of four sentences, each earning its place: it states the resource, lists event types, gives a usage scenario, clarifies the Classic-quiz-only restriction, and adds a caution about academic integrity. It avoids fluff and is front-loaded with the core purpose.

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?

For a read-only, single-submission event log tool, the description covers purpose, event types, access permission, ordering, and the Classic/New Quiz distinction that is crucial to invoking correctly. The only missing contextual piece is the exact response format/fields, but since no output schema exists, some detail is left uncovered; however, the description's guidelines still allow a confident invocation.

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?

Schema description coverage is 100%: every parameter (course_id, quiz_id, submission_id, attempt) has a description in the schema, including the 1-based intent for attempt. The description adds a general hint about the resource (event log for Classic Quiz submission) but doesn't significantly elaborate on parameter semantics beyond the schema. Since the schema does the heavy lifting, a baseline 3 is appropriate.

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 clearly states the verb ('Get'), the resource ('event log for a Classic Quiz submission'), and the specific scope ('Classic Quizzes only'). It also enumerates the event types (session_started, question_answered, question_flagged, page_blurred, page_focused), which differentiates it from siblings like get_quiz_submission_answers and get_quiz_question_responses by focusing on the chronological timeline rather than answer content.

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 explicitly says 'Use this to understand the timeline of a student's attempt' and names the alternative scenario: 'New Quizzes does not expose event logs via the Canvas REST API,' telling agents not to use this tool for New Quizzes. It also provides an important usage boundary: do not use event logs as the sole basis for academic-integrity conclusions, which is a clear normative guideline for when not to use the tool or to treat its output cautiously.

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