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

The description adds useful behavior beyond the annotations: it explains that the tool returns the membership Canvas reports and that adding an existing member returns the existing membership. It also warns that remove_group_member will not restore other group memberships Canvas may have changed, which is meaningful side-effect context.

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 three focused sentences with the primary action front-loaded. Every sentence contributes either purpose, idempotent return behavior, or a relevant removal caveat.

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 simple two-parameter mutation with annotations and no output schema, the description covers purpose, idempotency, return behavior, and a removal caveat. It could be strengthened with permission requirements or error behavior, but the essential calling context is present.

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?

Both parameters are fully described in the schema, including that user_id and group_id are Canvas IDs. The description adds no parameter-specific meaning beyond the schema, so the baseline of 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 gives a specific verb and resource: add a user to a group. It is clearly distinct from the sibling remove_group_member, which it explicitly references.

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 makes the intended use clear and names remove_group_member as the removal alternative. It does not explicitly state when not to use this tool or mention prerequisites such as group-management permissions.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is partly covered. The description adds real value beyond them by spelling out what the destructive path actually does (null removes the course's current grading standard) and what is returned (the updated course object).

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?

Four short sentences, front-loaded with the core action and followed by the ID source, the null semantics, and the return value. Each sentence carries information; only the return-value sentence is arguably redundant given the tool's obvious shape.

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 two-parameter mutation with no output schema, the description covers purpose, ID provenance, removal behavior, and return shape, with annotations carrying the destructiveness signal. A note on required permissions or the effect on existing assignment grades would make it fully complete.

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% and the schema's own grading_standard_id description already says 'or null to remove the current standard', so the description largely restates what the schema provides. It adds only the pointer to sibling tools as ID sources, which is the baseline-3 case.

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?

States a specific verb and resource ('Apply an existing grading standard to a course') and immediately names the sibling tools that produce the ID it consumes (create_grading_standard, list_grading_standards). An agent can distinguish this from those siblings without opening any schema.

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?

Tells the agent where to obtain grading_standard_id and explicitly covers the removal case (pass null). It gives clear positive context but does not state any when-not-to-use condition or permission prerequisite for the mutation.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the agent knows this is a mutating, externally-visible write. The description adds the return value ('the new rubric association') but does not disclose what a destructive attach overwrites (e.g. an existing rubric association) or any permission requirement, leaving a meaningful behavioral gap against the annotation bar.

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?

Two sentences, zero waste: the primary action is front-loaded and the routing rationale plus return value follow. Nothing extraneous.

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 correctly states the return ('the new rubric association'), and it covers the sharing rationale for a 6-param mutation. It stops short of noting permissions or the destructive overwrite behavior implied by the annotations.

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%, so all six parameters are already fully documented in the schema, including purpose, use_for_grading, and hide_score_total. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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?

States a specific verb (attach), resource (existing course rubric), and target (assignment), and explicitly frames the distinction from create_rubric. An agent can immediately tell it apart from create_rubric and delete_rubric without opening a schema.

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?

Names the alternative (create_rubric) and the condition that selects this tool over it (sharing one rubric across many assignments instead of duplicating). It does not, however, state prerequisites such as required permissions or whether the rubric must already exist in the course beyond the word 'existing'.

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

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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds substantial beyond-schema context: the exact severity taxonomy (error vs advisory), explicit limitations (no color-contrast checking, no list-misuse detection), the opt-in quizzes behavior, and required permissions. This is rich disclosure.

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 dense and long, but it is front-loaded with purpose and each clause earns its place by specifying checks, limitations, or permissions. Slight verbosity for a two-parameter tool keeps it below a 5.

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?

Despite no output schema, the description explains that findings carry a WCAG success criterion and severity level, and it scopes exclusions and permissions. An agent has everything needed to invoke it correctly and interpret results.

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 the baseline is 3. The description reinforces meaningfully that omitting `include` scans the default four sources and that `quizzes` must be passed explicitly for opt-in scanning, adding behavioral nuance beyond the raw schema text.

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?

States a specific verb (scan/audit) and resource (course content for WCAG 2.1 structural accessibility problems), and enumerates exactly what it detects. An agent can distinguish it from audit_course_links, check_course_setup, and Canvas's in-app Accessibility Checker without inspecting another schema.

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?

Gives clear context: requires instructor permissions, complements rather than replaces Canvas's in-app checker, and explains the quizzes opt-in. It does not explicitly route against sibling audit tools, but the usage conditions and exclusions are well stated.

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

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

Annotations already declare readOnlyHint=true, but the description adds real behavioral context beyond them: no outbound HTTP requests (structural checks only), the instructor-permission requirement, and the cost model (one extra Canvas API call per quiz). The 'no outbound HTTP requests' statement sits alongside openWorldHint=true, which is a nuance rather than a contradiction since the tool still calls the Canvas API.

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?

Front-loads what it scans and what it returns, then layers the quizzes nuance and the structural-check constraint. Every sentence carries information an agent needs; nothing is filler.

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?

No output schema exists, yet the description sketches the return shape (cross-course references plus empty/malformed URLs), states the permission prerequisite, and clarifies scope limits. For a 2-parameter read-only audit tool, that is sufficient for correct 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 coverage is 100%, and both parameters are fully documented in the schema itself, including the default four sources and the quizzes opt-in. The description restates the same semantics (defaults, opt-in quizzes, extra API cost) without adding format or syntax detail, so the baseline of 3 applies.

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?

States a specific verb+resource (scan a course's content for broken/outdated links and images), enumerates the scanned sources, and names the concrete failure class it detects (cross-course references after a course import). An agent can distinguish it from siblings like audit_course_accessibility, check_course_setup, or search_course_content without opening the schema.

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?

Gives clear context for when this applies: post-import stale-copy auditing and quizzes that break silently for students. The opt-in nature of `quizzes` is called out explicitly. It stops short of naming an alternative tool or stating when not to use this, 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.

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that: the return shape ("findings grouped by check with a plain-language detail per item") and an explicit permission requirement, both of which the annotations do not convey.

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?

Three sentences, front-loaded with the core action, then scope boundaries, alternatives, and prerequisites in descending order of importance. No filler or repetition; every clause carries routing or behavioral information.

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 takes on the burden of describing the return shape and does so. Combined with permission requirements and the explicit exclusion of submission/performance analysis, an agent has everything needed to call this correctly and interpret the result.

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 the baseline is 3. The description goes further by spelling out in plain language what each check identifier actually detects (e.g. "published assignments still accepting submissions after their due date"), which lets the agent choose a `checks` subset without guessing at enum meanings. It does not, however, restate that omitting `checks` runs all five.

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?

States a specific verb+resource ("Run a factual course-readiness report") and then enumerates the concrete problem classes it detects, so the agent knows exactly what this tool produces. It explicitly distinguishes itself from list_students_needing_attention and get_missing_submissions, which is critical in a sibling set this large.

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?

Gives an explicit when-not boundary ("config-health report only; it does not inspect student submissions or performance") and names the two alternative tools for that adjacent use case. It also states the prerequisite ("Requires instructor permissions in the course"), so the agent can route and gate correctly.

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

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

Annotations only flag destructiveHint/openWorldHint; the description adds the crucial non-idempotency warning (retries leave duplicate comments), the guarantee that grade/score are untouched, and the exact permission model versus grading rights. This is context beyond what the structured fields convey.

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 core action and non-idempotency warning are front-loaded and every sentence carries information. It is somewhat dense in the middle (permission clause), but no sentence is filler.

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 4-param mutation with no output schema, the description covers return shape, idempotency, side effects, permissions, and sibling routing. Nothing an agent needs to invoke it correctly is missing.

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 all four parameters are already documented in-schema. The description only echoes course_id/assignment_id/user_id in the grade_submission cross-reference and adds no new format or constraint semantics, so the baseline 3 applies.

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 first sentence states a specific verb and resource ('Add a text comment to a submission') and describes the return value (updated submission object with the new entry appended to submission_comments). It also explicitly contrasts with grade_submission, so an agent can distinguish it from the nearest 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?

It explicitly routes the agent: use grade_submission to change grade/score, and use list_submission_comments_needing_attention to find unanswered comments. It also spells out who is permitted to comment, which determines whether a call is even viable.

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

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

Adds significant behavior beyond the destructive/openWorld annotations: default workflow_state 'pending' is unpublished and invisible, publish is irreversible in Canvas, and there is no dedup against existing titles so repeated calls create duplicates. Permission requirements are also stated.

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?

Front-loaded with purpose and return value, and nearly every sentence carries useful constraint information. It is one dense paragraph though; splitting publish/dedup/permission caveats would improve scannability.

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 an 11-parameter mutation with no output schema, the description names the returned fields (id, title, workflow_state, context_codes), covers defaults, irreversibility, dedup behavior, and permission scope. Nothing an agent needs to call it safely is missing.

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 baseline is 3; the description earns extra by explaining the consequence of publish (irreversible), the meaning of participant_visibility (private vs protected so participants see each other), and the [start_at, end_at] ISO 8601 shape for new_appointments.

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?

Specific verb and resource: 'Create a new appointment group (Canvas Scheduler sign-up slots) in one or more contexts', plus what it returns. It is clearly distinguishable from update_appointment_group, which it names as the tool for adding slots later.

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?

Explicit routing: add slots up front via new_appointments or later with update_appointment_group; confirm with get_appointment_group before setting publish; permission required in every context. Covers both when-to-use and a concrete precondition to check.

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

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

Adds behavior far beyond the annotations: non-idempotency ("each call creates another assignment — Canvas assigns a new ID every time") with a duplicate-avoidance procedure, the instructor/TA permission requirement, and cross-field validation rules (lock_at after due_at, unlock_at before due_at). The destructiveHint/openWorldHint annotations are not contradicted; the description supplies the idempotency and auth context the annotations cannot express.

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?

Front-loaded with purpose and the non-idempotency warning, and every sentence carries actionable content (dedupe check, alternatives, date constraints, permissions). It is slightly dense and long for one paragraph, which keeps it off a 5.

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 12 parameters, no output schema, and only openWorld/destructive annotations, the description covers what the structured fields cannot: idempotency, permissions, and the cross-parameter date ordering rules. Remaining fields (published, points_possible, submission_types) are already documented at 100% in the schema, so nothing an agent needs is missing.

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 the per-field baseline is 3. The description earns extra credit by explaining the semantics of the three date fields together — they apply to every student, must be ISO 8601, and carry ordering constraints — plus it routes the differential-date use case away to other tools.

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?

Opens with a specific verb+resource ("Create a new assignment in a course") and immediately names the resulting object. It explicitly distinguishes itself from update_assignment, delete_assignment, create_assignment_override, and set_student_assignment_dates, so an agent can route correctly without opening sibling schemas.

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?

Gives explicit when-to-use (new assignment only), when-not-to-use (check list_assignments with search_term first; use update_assignment for changes; use create_assignment_override for per-section/group dates), plus a permission prerequisite. Alternatives and their selecting conditions are all named.

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

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

Annotations only declare openWorldHint and destructiveHint; the description goes far beyond with non-idempotency ('each call makes another group even when the name matches'), the empty-on-creation state, group_weight being inert unless the course weights by group, Canvas coercing bad weights to 0, the deliberate omission of drop rules with the reason, and the required permission.

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?

Front-loaded with purpose and return value before the caveats, and every sentence carries information. It is a single dense block of prose covering many clauses, which is harder to scan than a short bulleted caveat list, but nothing is padding.

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?

Covers everything an agent needs for a 5-param mutation tool with no output schema: what is returned, idempotency risk, prerequisites (course weighting setting), permission requirement, and an explicit rationale for a missing capability. No meaningful gap remains.

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 baseline is 3; the description nonetheless adds real meaning for group_weight (percent of final grade, conditionally effective, coerced to 0 when missing/non-numeric) and explains why a drop-rule parameter is absent. name, position and sis_source_id get no added semantics, keeping it short of a 5.

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?

States a specific verb and resource plus a parenthetical definition ('a gradebook category such as Homework or Exams') and the return shape (id, name, position, group_weight). It explicitly distinguishes itself from list_assignment_groups and update_assignment_group, so an agent can route without opening a schema.

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?

Gives explicit when-to-use and when-NOT-to-use guidance: read list_assignment_groups first, then use update_assignment_group for an existing group, and use create_assignment/update_assignment's assignment_group_id to populate it. It also names the exact alternative for drop rules.

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

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

Annotations supply destructiveHint=true and openWorldHint=true, and the description adds real behavioral context beyond them: a 422 error when a student-set override already exists, the partial-update semantics ('omit a date field to leave the corresponding date unchanged'), and the pseudonymization prerequisite. It stops short of warning that an existing override for the same target may be replaced or how to undo.

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?

Front-loaded with purpose, then constraints, then sequencing, then format — a logical order with little waste. It is fairly dense with rules, but each sentence carries distinct, non-redundant information.

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 9-parameter mutation with no output schema and only two annotations, the description covers the key constraints, error behavior, and prerequisites an agent needs to invoke it correctly. It omits permission requirements and expected response shape, which would round it out.

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 the per-parameter descriptions already carry most semantics. The description still reinforces value by surfacing the tool-level 'exactly one target' and 'at least one date' rules plus the ISO 8601 example format in a single place, though it does not add new per-parameter detail.

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?

States a specific verb and resource — 'Create a due-date / availability override for a specific assignment' — and immediately enumerates the three override target types. This clearly distinguishes it from sibling tools like list_assignment_overrides and set_student_assignment_dates.

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?

Gives explicit preconditions: exactly one of student_ids/course_section_id/group_id, at least one date field, ISO 8601 formatting, auditing via list_assignment_overrides to avoid a 422, and calling resolve_pseudonym first when pseudonymization is on. This is a near-complete decision and sequencing guide.

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

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

Beyond the annotations, the description discloses that the event is saved immediately with no draft or publish step, that duplicates are created on repeat calls, and that creating in the target context requires permission. These are meaningful behavioral details for a mutation tool, and they are consistent with the mutation-oriented annotation profile.

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 front-loaded with the core action and return value, then adds only decision-relevant details about context targeting, duplicate behavior, update alternatives, persistence, and permissions. Despite its length, each sentence carries useful information for correct invocation.

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?

There is no output schema, but the description names the key returned fields (`id`, `start_at`, `end_at`, `workflow_state`). It also covers permissions, duplicate behavior, persistence, and the relationship to sibling tools, leaving no important operational gap for this create operation.

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 the schema already explains all six parameters. The description adds meaningful semantic clarification for `context_code`, noting that it can target a course, group, user, or account context rather than only courses, which goes beyond the schema's course-shaped example.

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 states a specific verb and resource ('Create a new calendar event') and explicitly says it returns the created event object with named fields. It also distinguishes creation from updating and from listing existing events, so an agent can select it confidently.

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?

It explicitly says to check `list_calendar_events` first and to use `update_calendar_event` with the returned `id` when changing an existing event. It also warns that repeating the same create call produces a duplicate rather than an update, which gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations only declare openWorldHint/destructiveHint; the description adds real value beyond them by disclosing the async contract, the immediate return with an export ID and workflow_state 'created', and that the download link is time-limited. It never reconciles why destructiveHint is set, which for a pure export is an unexplained flag.

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?

Three tight sentences: purpose first, async contract second, next-step routing third. Every sentence carries information and nothing is padded.

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 correctly carries the return-value burden — export ID, initial workflow_state, and the downstream source of the download link. Parameters are fully covered by the schema, so nothing an agent needs to invoke the tool is missing.

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% and the enum values are fully documented in the schema, so the description's format list adds nothing new. Baseline 3 for a fully-covered 2-parameter schema.

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?

Uses a specific verb ('Start a Canvas course content export') plus the resource and supported formats (Common Cartridge / QTI / zip). An agent can distinguish it from the read-side siblings get_content_export and list_content_exports without opening a schema.

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?

Explicitly routes the agent onward, naming get_content_export as the polling tool and stating the condition (once the export finishes, to get the time-limited link). It lacks any 'when-not' guidance — notably no disambiguation from the sibling create_content_migration, which is the natural confusion case.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description usefully adds that the call is asynchronous, returns immediately, and yields a migration ID plus progress_url. It stops short of warning that a migration can overwrite/replace existing course content (the destructiveHint implication) or noting any permission prerequisites, which would be the higher-value additions.

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?

Two sentences, zero filler: the first names the operation and its variants, the second covers the async contract and the polling path. Front-loaded with the action, and every clause earns its place.

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 correctly compensates by describing the immediate return (migration ID, progress_url) and the polling workflow. It lacks any note on permissions or irreversible content replacement, so a complex, destructive, nested-object tool is not fully covered.

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%, so the baseline is 3. The description restates the migration types already enumerated in the migration_type enum and does not add syntax or format detail for settings, selective_import, or date_shift_options beyond what the schema documents.

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?

States a specific verb and resource ('Start a content migration') and enumerates the five concrete migration types (course copy, Common Cartridge, zip, QTI, Moodle), which maps directly to the migration_type enum. An agent can distinguish this from siblings like create_content_export or list_content_migration_types without opening the schema.

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?

Tells the agent what to do after invocation — poll get_content_migration or progress_url — which is explicit follow-up guidance. However, it never contrasts this tool with adjacent siblings such as create_content_export (export vs. import) or list_content_migration_types (to discover valid types), leaving that selection to inference.

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

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

Annotations only flag openWorldHint and destructiveHint; the description adds substantial undisclosed behavior: non-idempotency with duplicate-creation risk, silent dropping of start_at/end_at unless course-date restrictions apply (which this tool cannot set), and the account-level permission requirement. These are exactly the operational hazards an agent must know before calling.

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?

Front-loaded with purpose and return value, then the non-idempotency warning, then the date caveat. Four sentences, all earning their place, though the date sentence is tangled with nested clauses and could be split for readability.

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?

No output schema exists, but the description enumerates the returned fields. Combined with permission requirements, idempotency behavior, and the date pitfall, an agent has everything needed to call this correctly or route elsewhere.

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 the baseline is 3. The description additionally warns that start_at and end_at may silently not take effect and that update_course is the fallback, which is meaningful semantics the schema does not convey. It does not add anything for name, course_code, or account_id beyond the schema.

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?

States a specific verb and resource ('Create a new course in a Canvas account') plus what is returned (id, name, course_code, workflow_state, and inputs echoed). It is clearly distinguishable from siblings like update_course and list_courses, which are named directly.

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?

Explicitly states the non-idempotent behavior and names both alternatives with their conditions: use update_course to modify an existing course, or list_courses first to check for a matching course. The 'when not to call this twice' guidance is unambiguous.

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

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

Annotations only flag openWorldHint and destructiveHint; the description supplies far more: non-idempotency with no server-side dedupe by title, the silent downgrade of is_announcement to a plain topic with HTTP 200, and the tool's own throw-with-topic-ID failure behavior so the caller can verify via list_discussions/get_discussion. These are exactly the non-obvious failure modes an agent needs before calling a mutation.

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?

Front-loaded with purpose and return shape, then caveats, then sibling routing — good ordering with no filler. The is_announcement sentence is long and partially restates the schema field description, so it is dense rather than perfectly tight.

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?

No output schema exists, so the description compensates by naming returned fields. Combined with permission requirements, non-idempotency, and the silent-downgrade failure path, an agent has everything needed to invoke this correctly and interpret the outcome.

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 baseline is 3; the description still adds meaning by tying the title parameter to Canvas's lack of dedupe and by reinforcing that is_announcement's response field must be checked rather than the request assumed honored. It does not, however, cover delayed_post_at, published, or require_initial_post beyond what the schema says.

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?

States a specific verb and resource ('Create a new discussion topic in a course') and enumerates the returned fields (id, title, message, discussion_type, published, is_announcement, posted_at), which distinguishes it from sibling reads like get_discussion and list_discussions. An agent can pick it out of a large sibling list without opening the schema.

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?

Explicitly routes to alternatives: check list_discussions first to avoid duplicates, use update_discussion to modify, delete_discussion to remove, post_discussion_entry to reply. It also states the prerequisite (instructor/TA permission to manage discussions).

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

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

Annotations only declare openWorldHint and destructiveHint; the description adds the admin prerequisite, the pre-send descending sort, the Canvas singular/plural key mismatch, and the returned id's downstream use. These are meaningful behavioral details beyond the structured annotation fields.

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?

Front-loaded with purpose, then parameter constraints, then return and id usage; every sentence is information-bearing. It is slightly long due to Canvas POST/body key internals, but there is no filler.

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?

No output schema exists, so the description carries the return-value burden and does so by stating the created object includes its id and how to use it. It covers creation context, naming, admin requirements, and activation path.

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%, so the schema already documents every parameter. The description reinforces the 0–1 lower-bound value semantics with an example and adds the non-obvious pre-send sort order, though some of this repeats the schema.

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?

States a specific verb ('Create') and resource ('grading standard'), plus its scope (course or account). It also distinguishes itself from nearby tools by naming apply_grading_standard_to_course as the activation step for the returned id.

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?

Clearly explains that either course_id or account_id is required, that account context requires admin, and how to activate the result with apply_grading_standard_to_course. It lacks explicit when-not-to-use guidance or a direct comparison against list_grading_standards.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds that the new group starts empty and how to fill it, but says nothing about who may create groups (teacher vs. student permissions), duplicate-name behavior, or whether the created group's ID is returned — meaningful gaps for a create mutation.

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?

Three short sentences, zero filler, with the addressing constraint front-loaded before the discovery and follow-up hints.

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 should ideally say what comes back (notably the new group's ID, needed for add_group_member); it also omits permission requirements. Otherwise the creation workflow is adequately covered.

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 the baseline is 3; the description earns a small bump for restating the category-vs-course distinction at the point of use, though it duplicates the schema's own wording. join_level's category-dependent semantics are covered by the schema, not the description.

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?

States a specific verb and resource ('Create a group inside a group category') and immediately disambiguates the addressing key: group_category_id, not course ID. An agent can distinguish it from create_group_category and add_group_member without opening a schema.

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?

Explicitly routes the agent to list_group_categories to find the required ID and to add_group_member for populating the group. That is a concrete when/how sequence plus a named alternative for membership operations.

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

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

Annotations already declare destructiveHint and openWorldHint, so the safety profile is carried by structured data. The description adds only the useful detail that the resulting category is 'empty' (no groups auto-created), but says nothing about who may create categories, whether duplicate names are allowed, or what happens on failure in a course without group permissions.

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?

A single short sentence with no filler; the key qualifier 'empty' is front-loaded and immediately actionable.

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 two-parameter create tool with annotations present this covers the core action, but there is no output schema, so the description should mention that the created category (and its id) is returned — an agent needs that id to subsequently create groups in the new set. Permission expectations are also absent.

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%: both course_id and name are fully documented in the schema. The description neither repeats nor enriches them, so the baseline 3 applies.

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?

States a specific verb and resource ('Create a new, empty group category') and adds the Canvas synonym 'group set' plus the meaningful qualifier 'empty', which distinguishes it from a factory that also provisions groups. It does not explicitly contrast with siblings like list_group_categories or create_group, but the operation is unambiguous.

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 gives no when-to-use guidance, no prerequisites (e.g. course edit permissions), and does not mention alternatives such as create_group or list_group_categories, which sit right next to it in the tool list. The agent must infer all context from the name alone.

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

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

The description adds substantial behavior beyond annotations: duplicate creation risk, unpublished-by-default behavior, silent dropping of invalid prerequisite IDs, return value containing the new Canvas ID, and required instructor/TA permissions. These details materially help an agent understand side effects and constraints.

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 front-loaded with the core action and then covers each important caveat in sequence. Every sentence provides operational value, with no filler.

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 lack of an output schema, the description explains the return value. It also covers permissions, duplicate behavior, publishing defaults, prerequisite gotchas, and the follow-up tool needed to add content, which is complete for this mutation tool.

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 the baseline is 3. The description adds non-obvious semantics for prerequisite_module_ids, specifically that invalid IDs are silently ignored, which goes beyond the schema's generic 'IDs of modules' wording.

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 states a specific verb and resource: 'Create a new module in a course.' It also distinguishes the tool from siblings by naming list_modules, update_module, and create_module_item, so an agent can select it without ambiguity.

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?

It gives explicit when-to-use guidance: check list_modules first to avoid duplicates, use update_module to publish, and use create_module_item to add content afterward. Permission requirements are also stated.

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

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

Goes well beyond the sparse annotations by disclosing non-idempotency ('calling it twice with the same title adds two items, not one'), the return payload ('returns the created module item, including its new Canvas ID'), and the authorization requirement. These are exactly the behavioral traits an agent needs before firing a write call.

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?

Front-loads purpose, then idempotency warning, then the type-to-field mapping, then sibling routing, then permissions — a logical order with no filler sentences.

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 an 8-parameter mutation tool with no output schema, the description covers what is created, what comes back, how to identify content per type, permission requirements, and follow-up operations. Nothing material is missing.

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 baseline is 3, but the description adds real value by mapping each `type` value to its required identifying field (`page_url`, `content_id`, `external_url`, or none for SubHeader) and notes Pages are addressed by slug rather than ID. Only `position` is left unexplained, which the schema handles.

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?

Opens with a specific verb and resource ('Add an item to a module') and enumerates the eight item types, so the agent knows exactly what it creates and what scope it covers. Clearly separable from sibling tools like create_module or create_page.

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?

Explicitly routes the agent to `list_module_items` to inspect existing items and to `update_module_item`/`delete_module_item` for changes, which distinguishes this tool from its closest siblings. It also states the permission precondition (instructor/TA).

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

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

Annotations declare destructiveHint=true and openWorldHint=true; the description goes well beyond them by warning that repeated calls create duplicate quizzes, that Canvas replaces the multiple_attempts sub-object wholesale (omitted sub-fields are cleared), and that IP filtering and result_view_settings are unsupported. Those are exactly the failure modes an agent needs to know for a write tool.

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?

Purpose and return value are front-loaded, then workflow, then caveats — a sensible ordering with no filler. It is somewhat long and restates the multiple_attempts whole-object replacement that the schema already spells out, so one sentence is redundant.

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 9-parameter mutation tool with nested objects and no output schema, the description covers what is created, what is returned, what happens on retry, which follow-up tools exist, permission requirements, and unsupported settings. Nothing needed to call it safely is missing.

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 the baseline is 3, but the description adds two things the schema cannot: the summary of what quiz_settings covers (calculator, shuffle, time limit, access code, one-at-a-time, attempts) and the explicit statement that IP-address filtering and result_view_settings are not settable. The multiple_attempts replacement note duplicates the schema's own text, which caps it below 5.

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?

States a specific verb and resource ('Create a New Quiz (LTI) in a Canvas course') and immediately distinguishes it from the Classic-quiz siblings: list_quizzes, get_quiz, and delete_quiz only read and delete that older type. It also names the returned identifiers (id, assignment_id), so an agent knows exactly what it gets back.

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?

Gives an explicit lifecycle: create here, then create_new_quiz_item for questions, update_new_quiz for title/dates/points, delete_new_quiz to remove. It also names the when-not path ('not idempotent, so check list_quizzes before retrying') and states the permission prerequisite.

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

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

Beyond the destructiveHint/openWorldHint annotations it discloses the non-idempotent, append-only behavior ("each call adds another item"), Canvas rate-limiting with a concrete serial/batch-of-50 workaround, the publish-independence rule (an item has no publish setting; visibility follows quiz publish state), and the required permission. These are exactly the traits an agent cannot infer from structured fields.

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?

Front-loaded with the operation and return shape, then constraints and sibling routing. Dense but nearly all of it earns its place; the type enumeration is long, though it pays for itself by sparing a schema read.

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?

Covers return contents (item_id, position, points_possible, body incl. scoring_data), the create-only semantics, idempotency, rate limits, permissions, and sibling alternatives — everything needed to invoke this 5-parameter mutation correctly without an output schema.

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 already 80%, and the description adds real value on top: assignment_id is clarified as a New Quiz identifier rather than a Classic Quiz ID, and the interaction_type_slug variants are explained semantically (e.g. ordering choices are listed in correct sequence and Canvas shuffles display, rich-fill-blank blanks written as backticked correct answers).

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?

States a specific verb and resource ("Create one item (question) in a New Quiz (LTI)") and enumerates all eight supported item types with one-line semantics for each. An agent can distinguish this from update_new_quiz_item, delete_new_quiz_item, and create_new_quiz without opening a schema.

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?

Explicitly routes to siblings: list_new_quiz_items before retrying an uncertain create, update_new_quiz_item for changes, delete_new_quiz_item for removal, create_new_quiz first if the quiz doesn't exist. It also gives the precondition (permission to manage quizzes) and the assignment_id provenance rule (from list_assignments/get_assignment filtered on is_quiz_lti_assignment, not a Classic Quiz ID).

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

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

Goes well beyond the annotations by disclosing the non-idempotent write semantics, that Canvas does not deduplicate by title, and the required permission to manage wiki content. It also names the returned url slug that other tools depend on, which is not derivable from destructiveHint/openWorldHint.

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?

Front-loaded with the core action, then the idempotency caveat, then alternatives, then the permission note — a sensible order with no filler. It is dense but each clause contributes; the single very long sentence slightly hurts scannability.

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?

Covers everything an agent needs: prerequisites, duplicate risk, sibling routing, and downstream use of the returned slug. With an output schema present, it correctly does not waste space narrating the full return shape.

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%, so the parameters are already documented. The description restates the parameter set (title, optional HTML body, published state, editing_roles) without adding format or validation guidance, so it earns only the baseline.

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?

States a specific verb and resource ('Create a new wiki page in a course') plus the key fields supplied and the created artifact returned. It explicitly names the sibling operations (get_page, update_page, delete_page, list_pages, create_module_item) so it is distinguishable without opening any schema.

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?

Gives an explicit when-not ('Use update_page to edit an existing page instead of creating a new one') and a concrete duplicate-avoidance path ('check list_pages first'). It also tells the agent how a follow-on tool consumes the result (create_module_item's page_url with type Page).

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

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

Annotations only flag openWorldHint and destructiveHint; the description adds the post-write state (workflow_state 'assigned'), the exact returned fields, and the authorization level required. It does not contradict the destructive/mutating annotation — the tool does write data.

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?

Front-loaded with what is created and returned, followed by the ID disambiguation, then alternatives. Every sentence carries information, though the assessor_id/user_id explanation takes two clauses where one tighter sentence could suffice.

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 supplies the return shape and initial state, plus the permission and existence preconditions. Nothing an agent needs to invoke this correctly is missing.

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 already 100%, but the description resolves a genuine semantic trap the schema cannot: the user_id you pass is the reviewer, who appears as assessor_id in the response, while the response's user_id is the reviewee. That is material meaning beyond the schema's 'Canvas user ID of the reviewer to assign.'

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?

States a specific verb and resource ('Assign a Canvas user as a peer reviewer for one submission') and names the created artifact's fields. It is immediately distinguishable from list_peer_reviews, get_submission_peer_reviews, and delete_peer_review, which are all named explicitly.

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?

Explicitly routes the agent: use list_peer_reviews for the whole assignment, get_submission_peer_reviews for one submission, delete_peer_review to unassign, and check first 'before assigning another reviewer.' It also states the prerequisite that submission_id must already exist and the instructor/TA permission requirement.

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

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

Annotations already carry the safety profile (destructiveHint=true, openWorldHint=true, consistent with a create). The description adds real behavioral value beyond that: it documents the return shape ({ rubric, rubric_association? }) and explains that rubric_association.id is the association_id consumed by submit_rubric_assessment, enabling correct chaining. It omits permission/auth requirements, so not a 5.

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?

Three tight, front-loaded sentences with zero filler: the action, the optional linking behavior, then the return contract. Every clause earns its place by either describing behavior or enabling downstream chaining.

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 nested criteria/ratings objects, four parameters, and no output schema, the description does the necessary work by describing the return payload and the association linkage. It stops short of documenting authorization or course-state prerequisites, leaving a small gap for a mutating, open-world tool.

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%, so the baseline is 3 and the schema already documents title, criteria, ratings, and association fields. The description adds meaning above the schema by tying the nested association output back to submit_rubric_assessment's association_id, a workflow-level semantic not present in the schema.

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?

States a specific verb+resource ("Create a new rubric in a course") with the composed entity (criteria and rating levels), which separates it from the read/delete rubric siblings. It does not explicitly distinguish itself from attach_rubric, the closest overlapping sibling, so it falls just short of a 5.

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 notes the association can be linked "immediately" and otherwise is optional, which implies usage context. However, it never states when to use this versus attach_rubric or whether a course must already exist, leaving the agent to infer alternatives.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, but the description goes well beyond: it discloses the exact blast radius (all time slots and reservations canceled, every signed-up participant emailed), irreversibility ('cannot be recovered afterward'), and the required permission scope ('manage the Scheduler in the group's context'). It also states the return value (deleted group object).

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?

Four sentences, each carrying distinct load: action+side effects, irreversibility, parameter note, prerequisite lookup, and permission. The destructiveness warning is front-loaded before the parameter and lookup guidance.

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 destructive, side-effecting tool with no output schema, the description covers what gets destroyed, who gets notified, reversibility, auth requirements, how to find the id, and the return value. Nothing an agent needs before calling is missing.

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 baseline is 3; the description adds marginal value on cancel_reason (it lands in the cancellation email to participants) and useful guidance on how to obtain appointment_group_id. It does not clarify the integer-or-string ID union, but the schema covers that.

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?

States a specific verb+resource ('Delete an appointment group by id') and immediately enumerates the cascade (slots, reservations) and return value. Clearly distinct from sibling update_appointment_group and get_appointment_group, and from delete_assignment/delete_rubric by naming the exact resource.

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?

Explicitly routes the agent: 'Find the id with list_appointment_groups' and 'check list_appointment_group_users or list_appointment_group_groups first if you need to know who will be notified.' Both the prerequisite lookup tool and the conditional pre-check tool are named.

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

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

Although annotations already declare destructiveHint=true, the description adds meaningful behavioral context: deletion is permanent and cannot be undone, no assignment object is returned, only an acknowledgement, and instructor/TA permission is required. These are practical details an agent needs before invoking a delete operation.

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 front-loads the permanent destructive action and then adds only high-value details: return behavior, alternatives, ID behavior, and permission requirements. Every sentence contributes to correct tool selection or invocation.

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 destructive mutation tool with annotations already covering safety hints and a fully described schema, this description fills the remaining gaps: irreversibility, lack of returned object, permission requirements, and sibling alternatives. No output schema exists, and the description explains the acknowledgement-only response adequately.

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 course_id and assignment_id are already documented by the schema. The description mentions the course and assignment context but does not add format, identifier, or validation details beyond the schema, so the baseline of 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 states a specific verb and resource ("Permanently delete an assignment from a course") and makes the scope clear. It also distinguishes deletion from updating and creation, so an agent can tell it apart from nearby assignment-related siblings.

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?

It explicitly says to use update_assignment to change an assignment rather than remove it, and create_assignment to make a new one. It also notes the Canvas ID consequence, which helps an agent choose the correct path rather than deleting and recreating.

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

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

The annotations already declare destructiveHint=true and openWorldHint=true. The description adds that the action is 'permanent,' which reinforces irreversibility, but it does not cover permissions, side effects on discussion entries, or any rate limits. With annotations covering the safety profile, this is a modest addition.

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?

Two short sentences with zero waste. The core action is front-loaded and the permanence warning follows immediately, making it efficient and easy to scan.

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 simple two-parameter destructive tool with full schema coverage and annotations declaring destructiveness, the description provides the essential action and permanence warning. It is nearly complete, though it could mention effects on associated discussion entries or required permissions.

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%, so both parameters are fully documented in the schema. The description adds no parameter-level detail (e.g., ID format or constraints), which is consistent with the baseline 3 when schema coverage is high.

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 states a specific verb ('Delete') and resource ('discussion topic') with scope ('from a course'), clearly distinguishing it from siblings like update_discussion and list_discussions. An agent can identify the operation without opening the schema.

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?

No explicit when-to-use guidance or alternatives are mentioned. The description only restates the action; it does not say when to choose this over update_discussion or how to confirm intent before a permanent deletion.

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

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

Beyond the destructiveHint annotation, it explains that the deletion is permanent, there is no undelete, a deleted file object with last known metadata is returned, and a replacement upload receives a different Canvas ID. These are substantive behavioral details that an agent could not infer from the annotations alone.

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?

Three sentences, front-loaded with the destructive action and irreversibility, followed by the replacement alternative and permission requirement. Every sentence contributes actionable information with no waste.

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 single-parameter destructive tool with no output schema, the description covers deletion semantics, return value, permission prerequisites, and replacement workflow. Nothing material is missing for an agent to call it safely and correctly.

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 single parameter is fully documented by the input schema at 100% coverage, where file_id is described as 'The Canvas file ID'. The description only restates 'by ID' and adds no syntax, format, or validation details beyond the schema, so the 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 states a specific verb and resource ('Permanently delete a file by ID') and distinguishes the operation from siblings like upload_file, get_file, and download_file by emphasizing permanence and replacement behavior. An agent can identify the tool's role without opening any schema.

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?

It gives clear usage conditions: requires permission to manage files in the course, cannot be undone, and upload_file is the alternative for restoring a replacement. It does not explicitly say when not to delete or recommend inspecting a file first, so it falls just 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.

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

Annotations already declare destructiveHint and idempotentHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond them: members are removed but stay enrolled in the course, the category survives, and re-creating a group yields a different one. It does not mention required permissions or whether related group discussions/assignments are affected.

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?

Three short sentences, front-loaded with the destructive verb, and each sentence conveys a distinct fact (members removed, enrollment preserved, category preserved, no restoration). Zero waste.

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 single-parameter destructive delete with no output schema, the description covers the main thing an agent needs: what is destroyed and what survives. It could go further on prerequisites (permissions, ownership role) and side effects on group-scoped content.

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?

Only one parameter (group_id) with 100% schema description coverage, so the schema already documents it fully. The description adds no format or sourcing hints for the ID. Baseline 3 is appropriate when the schema does the work.

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?

States a specific verb and resource ('Permanently delete a group') with clear scope. It does not distinguish itself from nearby siblings like remove_group_member or delete_appointment_group, but the action itself is unambiguous.

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 explains consequences but gives no guidance on when to use this versus remove_group_member (to remove one student) or other group-related deletion tools. An agent must infer the selection criteria from sibling names alone.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's job is to add specifics — and it does: it names the exact object graph that is destroyed versus preserved, and warns there is no single inverse. That is precisely the context annotations cannot convey.

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?

Three sentences, each front-loaded and load-bearing: the action, the deletion boundary, and the recovery cost. No filler or restatement of the name.

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 two-param destructive tool with no output schema, the description covers everything an agent needs: what is deleted, what is not, and how costly reversal is. Nothing relevant is missing.

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?

Both parameters (course_id, module_id) are fully documented in the schema at 100% coverage, so the baseline of 3 applies. The description adds no syntax or formatting detail beyond the schema, nor any guidance on resolving IDs.

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?

States a specific verb and resource ("Permanently delete a module from a course") plus the exact scope ("including its ordered list of module items"), which cleanly separates it from the sibling delete_module_item that removes a single item. An agent can pick the right tool without opening the schema.

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 sets clear boundaries by enumerating what survives (assignments, pages, quizzes, files, discussions) and what dies (ExternalUrl, ExternalTool, SubHeader items), which is effectively when-this-is-safe guidance. It stops short of explicitly naming delete_module_item or update_module as the alternatives for narrower operations.

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

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

Annotations declare destructiveHint and idempotentHint, but the description adds crucial behavior beyond them: for ExternalUrl, ExternalTool and SubHeader items the content itself is deleted, while for Assignment, Page, Quiz, File and Discussion items only the link is removed and the underlying content survives. This is exactly the kind of consequence disclosure an agent needs before calling a destructive tool.

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?

Two compact sentences plus a one-clause recovery hint. The core action is front-loaded, the critical distinction follows immediately, and every sentence earns its place.

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 destructive module-item deletion with no output schema and full schema coverage, the description supplies the missing behavioral nuance: which item types lose content versus only a link, and how to recover via create_module_item. Nothing essential for correct invocation is missing.

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%, so course_id, module_id and item_id are already documented in the schema. The description adds item-type behavior but no additional syntax, format, or constraint details for the parameters themselves, making the baseline 3 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?

States a specific verb ('Remove') and resource ('an item from a module'), and distinguishes the tool from siblings like create_module_item by naming the re-add alternative. The type-dependent outcome further sharpens what 'remove' means here.

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?

Provides clear context for when to use it and what happens by item type, and names create_module_item for re-adding. It does not explicitly state when not to use it (e.g., prefer update_module_item to modify rather than remove), so it falls short of 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is known. The description's 'This action is permanent' reinforces destructiveness but is largely redundant, and it never mentions the idempotent behavior or what else (items, submissions) is removed with the quiz.

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?

Three short sentences, front-loaded with the action and resource, then the permanence warning, then the parameter caveat. Every sentence earns its place with no filler.

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 destructive tool with no output schema, the description covers what is deleted, that it is permanent, and which ID to supply. It could still note required permissions or side effects (e.g. associated items/submissions), but nothing essential for a correct call is missing.

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 both parameters are already documented, but the description adds genuine disambiguation by warning to pass assignment_id rather than quiz_id — a real trap given the sibling quiz tools. It does not clarify the course_id vs assignment_id relationship beyond that.

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?

States a specific verb (Delete) and a precise resource (New Quiz (LTI) in a Canvas course), and the '(LTI)' qualifier plus the assignment_id note clearly separate it from the classic-quiz sibling delete_quiz and from delete_new_quiz_item. An agent can identify the tool without opening any schema.

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?

Usage is implied by naming the resource type, and the 'Use assignment_id (not quiz_id)' note helps route between similar deletion tools. However, it never explicitly says when to choose this over delete_quiz or delete_new_quiz_item, nor what prerequisites (role/permission) apply.

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

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

Annotations already flag destructiveHint=true, but the description adds the crucial detail that there is no undo and no restoration tool, plus the exact return shape ({ success: true } with no deleted item echoed back). This is precisely the extra context annotations cannot convey.

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 irreversible/destructive warning and the identity of the resource are front-loaded, and each following sentence adds a distinct piece of routing or prerequisite information with no padding.

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?

No output schema exists, yet the description supplies the return value, the irreversibility, the ID discovery path, the Classic-vs-New-Quiz disambiguation, and the permission requirement — everything an agent needs before calling a destructive tool.

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 all three parameters are documented, but the description still adds real semantic value: assignment_id is a New Quiz assignment (filtered on is_quiz_lti_assignment, from list_assignments/get_assignment) and explicitly not a Classic Quiz ID. item_id sourcing is also given. Slightly short of 5 only because course_id gets no added meaning.

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?

States a specific verb and resource: 'Permanently delete one item (question or stimulus) from a New Quiz (LTI) by its item_id', and explicitly scopes it to New Quiz LTI items rather than the many other deletable resources among the siblings.

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?

Gives the prerequisite lookup path ('Find item_id with list_new_quiz_items or get_new_quiz_item') and names two alternatives with their conditions: delete_new_quiz for the whole quiz, update_new_quiz_item if you only want to modify. It also states the permission needed to manage quizzes.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the agent knows this is a destructive operation. The description adds the specific behavioral detail that the action is permanent, but does not mention cascade effects, permission requirements, or whether special pages (e.g., front page) are protected. Moderate added value over annotations.

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?

Two short sentences, front-loaded with the action and followed by the permanence warning. Every word earns its place with no filler.

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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. For a two-parameter delete tool the description is nearly complete, though it could note whether deletion is reversible/undoable or subject to restrictions.

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%, so both course_id and page_url are fully documented in the schema itself. The description adds no parameter-level detail beyond what the schema provides, making the baseline of 3 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?

States a specific verb ('delete'), resource ('wiki page'), and scope ('from a course'), which cleanly distinguishes it from adjacent siblings like get_page, update_page, and create_page. An agent can identify the operation without opening the schema.

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?

Usage is implied by the clear delete-a-page purpose, but the description offers no explicit when-to-use guidance, prerequisites, or conditions under which deletion might be disallowed. No alternative tool is needed for this operation, so the omission is minor.

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

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

Despite annotations already marking destructiveHint=true and openWorldHint=true, the description adds substantial behavioral detail: only the peer-review relationship is removed, the submission and assignment remain untouched, Canvas's response body is discarded, and reversal creates a new id with workflow_state reset to assigned. This is exactly the kind of scope, side-effect, and permission context an agent needs.

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 front-loaded with the core removal action and then layers in scope, reversal, ID lookup, and permissions. Every sentence carries useful information, though it is denser and longer than strictly necessary for a four-parameter deletion tool.

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 and only sparse annotations, the description carries the full burden well: it explains the mutation scope, return behavior, permission requirement, and reversal path. An agent has enough information to invoke it correctly without needing additional context.

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 all four parameters are already documented by the input schema, making 3 the baseline. The description adds little parameter-level detail beyond identifying user_id as the reviewer to remove, and its mention of an assessor_id/user_id pairing is slightly at odds with the schema, which exposes only user_id.

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 states a specific verb and resource: remove a peer-review assignment from one submission, unassigning that reviewer. It also distinguishes the scope from content deletion and names the related create/list tools, so an agent can tell what this tool does versus siblings.

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?

It gives clear operational context: use list_peer_reviews or get_submission_peer_reviews to find the reviewer's user_id, and re-create with create_peer_review if needed. It also states the instructor/TA permission requirement. It does not explicitly state when-not-to-use conditions, so it falls short of the top score.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds real value by disclosing the blast radius — child questions and all student submissions are removed, not just the quiz shell. It stops short of stating auth/permission requirements, so it is a strong 4 rather than a 5.

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?

Two sentences with zero filler. The destructive scope is front-loaded, and the classic-vs-new-quiz routing is saved for the second sentence where it belongs as a disambiguation.

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 two-parameter delete tool with annotations covering the danger profile and no output schema to explain, the description covers everything an agent needs to call it correctly: what it deletes, how much it deletes, and which sibling to use instead. Only permission/authorization prerequisites are unaddressed.

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%, and both required parameters (course_id, quiz_id) are documented in the schema itself, so the baseline is 3. The description reinforces that quiz_id means a Classic quiz and that course_id scopes the deletion, but adds no format or constraint detail beyond the schema.

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?

States a specific verb and resource ('permanently delete a Classic quiz from a course') and immediately bounds the scope by enumerating what is destroyed — questions and every student submission. It explicitly distinguishes itself from the sibling delete_new_quiz, so an agent can route without opening either schema.

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?

Gives an explicit selection condition — 'Classic Quizzes only' — and names the alternative tool for the New Quiz (LTI) case. This is exactly the when-this/when-other guidance the dimension asks for, with nothing left to inference.

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

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

Annotations already establish destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds the irreversibility qualifier 'permanently' and the Classic-quiz-only restriction, which sharpens the blast radius. It does not, however, add anything about side effects on existing submissions or whether the deletion is recoverable.

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?

Two sentences, zero filler, with the destructive action front-loaded and the disambiguation clause placed immediately after. Every word earns its place.

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 needed for a delete and all three required params documented, the definition is nearly complete; annotations carry the safety profile. The only missing nuance is the downstream effect of removing a question from an already-administered quiz.

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