Set Student New Quiz Accommodation

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

Annotations include destructiveHint: true and openWorldHint: true, which already signal mutating and broad effects. The description goes beyond by explaining behavior: course-level is a single API call, per-quiz fans out sequentially, partial failures are tolerated, and Canvas errors on the course-level path propagate as top-level errors without an envelope. It also discloses the return envelope structure. The only minor gap is not detailing what happens to existing accommodations (overwrite? merge?), but the provided details are substantial.

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 information-dense but well-organized, front-loading the core purpose and scope. It uses clear segmentation (course-level vs per-quiz, Classic vs New) and keeps sentences purposeful. Slightly long but each sentence contributes necessary detail; no redundancy.

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?

Given the tool's complexity (two modes, error handling, envelope), the description covers critical operational details: fan-out behavior, failure tolerance, error propagation, envelope shape, user_id resolution, and differentiation from Classic Quizzes. With a 100% schema and no output schema, this is complete enough for an agent to call correctly. Minor missing details like exact response fields for failed[] are not essential.

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 coverage is 100%, so parameters are already documented. The description adds significant value by explaining the time_multiplier is a ratio (e.g., 1.5 for 1.5×), clarifying that extra_attempts is additional attempts beyond default, and the meaning of omitting assignment_ids (course-level). It also adds clarification that time_multiplier must be >1.0. This goes beyond schema descriptions.

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 tool applies a time and/or attempts accommodation for students across New Quizzes. It distinguishes between course-level and per-quiz modes h, explicitly names the sibling tool (set_student_quiz_accommodation) for Classic Quizzes, and specifies the target resource (New Quizzes). This makes the purpose unmistakable and separates it from the Classic Quiz sibling.

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 provides explicit when-to-use (New Quizzes) and when-not-to-use (Classic Quizzes, directing to set_student_quiz_accommodation). It explains the two modes (course-level vs per-quiz with assignment_ids) and even a prerequisite (resolve_pseudonym if pseudonymization is enabled). This is exceptionally clear guidance.

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