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

Annotations declare destructiveHint=true, and the description adds meaningful behavioral detail: applying a standard makes the gradebook use it, and passing null removes the current standard. It also discloses the return value ('Returns the updated course object'), which supplements the annotations even if it doesn't elaborate on permissions or broader side effects.

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 sentences and each one earns its place: what the tool does, how to supply the ID, and the special null behavior plus return value. It is front-loaded with the core purpose and contains 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 simple two-parameter mutation tool, the description covers the operation, parameter sourcing, removal behavior, and return type. With no output schema, it appropriately states that an updated course object is returned. The combination of annotations, schema, and description is sufficient for an agent to invoke this tool 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?

Schema description coverage is 100%, so the baseline is 3. The description adds extra value by telling the agent that grading_standard_id should come from create_grading_standard or list_grading_standards, and it reinforces the null-removal semantics already present in the schema. This goes slightly beyond the schema's bare parameter descriptions.

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

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

The description clearly states the action ('Apply an existing grading standard to a course'), the specific resource, and the intended effect ('so the gradebook uses it'). It also distinguishes itself from related tools like create_grading_standard and list_grading_standards by focusing on application/removal rather than creation/listing.

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 provides clear context on when to use the tool, including how to obtain the grading_standard_id and that passing null removes the standard. It does not explicitly state when not to use this tool or list alternatives, but the context is strong enough for an agent to distinguish it from create/list 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 readOnlyHint=true and openWorldHint=true, and the description aligns with these (scanning is read-only, and the tool is open-world in that it doesn't cover everything). The description adds valuable context beyond annotations: it explains the tool's limitations (structural checks only, no color contrast), the severity levels (error vs advisory), and the opt-in behavior for quizzes. It doesn't describe the exact output format, but the absence of an output schema and the rich detail provided justify a 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?

The description is a single, well-structured paragraph that front-loads the core purpose, then details the specific checks, limitations, opt-in behavior, and relationship to alternatives. Every sentence adds meaningful information without redundancy. It's longer than the TDQS 4.3 example but appropriately so given the tool's complexity.

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

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

Given the tool's complexity (multiple content types, multiple issue categories, opt-in parameter, limitations, and relationship to an alternative), the description is remarkably complete. It covers what the tool does, what it doesn't do, when to use it, and what permissions are needed. The absence of an output schema is compensated by the description's clarity about the types of findings (WCAG criterion + severity).

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% (both parameters are described in the schema). The description adds value by explaining the default behavior (omitting 'include' scans the default four sources) and the opt-in nature of 'quizzes', which goes beyond the schema's enum listing. However, the description doesn't add much about 'course_id' beyond what the schema provides, so a 4 is appropriate.

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

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

The description clearly states the tool scans course content for WCAG 2.1 accessibility issues, listing specific content types and specific problem categories. It distinguishes itself from the sibling audit_course_links by focusing on accessibility rather than links, and from Canvas's in-app checker by noting it complements rather than replaces it.

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

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

The description explicitly states when to use this tool (to scan for structural accessibility issues), what it does not do (no color-contrast checking, no list-misuse detection), and how it relates to alternatives (complements Canvas's in-app Accessibility Checker). It also specifies the opt-in 'quizzes' parameter and the permission requirement (instructor 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 declare readOnlyHint=true and openWorldHint=true, and the description adds valuable context: it performs structural checks only (no outbound HTTP requests), requires instructor permissions, and explains that quizzes are opt-in due to extra API calls. It doesn't contradict annotations and adds behavioral details beyond them.

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

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

The description is well-structured and front-loaded with the core purpose, then details the optional quizzes behavior, and ends with constraints. Every sentence adds value without redundancy, making it efficient and easy to parse.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description is complete: it covers what is scanned, the optional quizzes behavior, the nature of findings (cross-course references, empty/malformed URLs), constraints (no HTTP requests, permissions), and the rationale for opt-in quizzes. No gaps remain for an agent to misuse it.

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% with detailed descriptions for both parameters. The description adds meaning by explaining the default behavior (four content types) and the implications of including quizzes (extra API calls, silent breakage for students). This goes beyond the schema's basic enum listing.

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

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

The description clearly states the tool scans a course's content for broken or outdated links and images, listing specific content types and the optional quizzes inclusion. It distinguishes itself from siblings like audit_course_accessibility and check_course_setup by focusing on link integrity and structural checks.

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

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

The description explicitly explains when to use the tool (to find broken links, especially cross-course references after imports) and when not to (no outbound HTTP requests, structural checks only). It also notes the opt-in nature of quizzes and the permission requirement, providing clear context for selection.

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 and openWorldHint=true, so the read-only nature is covered. The description adds valuable behavior beyond this: it is 'factual,' returns findings 'grouped by check,' and explicitly excludes student submission data. It also states the permission requirement, which is not in annotations. However, it does not describe exact output shape or rate limits, 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?

Two sentences: the first lists the checks and states the report's purpose, the second clarifies scope and gives alternatives. No redundant wording, front-loaded with the main action. 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 read-only report tool with no output schema, the description gives a clear picture: what problems it finds, that it returns findings grouped by check with plain-language details, what it does not cover, and permission requirements. This is complete context for an agent to select and invoke the 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 schema already documents both parameters well. The description lists the specific check names in its prose, which helps a user understand what the 'checks' parameter values mean, but it doesn't add syntax or format details beyond the schema. 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 uses a specific verb ('Run') and resource ('course-readiness report') and enumerates exactly what configuration problems it surfaces (missing due dates, unpublished items, etc.). This clearly distinguishes it from sibling tools like health_check and list_students_needing_attention.

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 states when to use ('config-health report') and when not to use ('does not inspect student submissions or performance') by naming alternatives (list_students_needing_attention / get_missing_submissions). Also notes the permission requirement ('instructor permissions'), which is practical usage 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?

The annotations include destructiveHint=true, which signals that the tool modifies data. The description does not add additional context about side effects, permissions, or reversibility, but it does not contradict the annotation.

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

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

The description is a single, concise sentence with no unnecessary words or repetition. It is perfectly sized for the tool's simplicity.

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?

The description does not mention the tool's return value or any preconditions. Since there is no output schema, the description should hint at what the response will be (e.g., success message or comment object), but it does not, leaving a gap.

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 input schema covers all four parameters with clear descriptions (e.g., 'The Canvas course ID'). The description adds no additional meaning beyond the schema, so it remains at the baseline for high schema coverage.

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

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

The description clearly states the action 'Add a text comment to a submission' and identifies the resource (submission). It is specific and distinguishes from similar tools like grading or rubric submission.

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

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

The description provides no context on when to use this tool versus alternatives, such as grading or other commenting tools. It lacks any 'use when' or 'instead of' 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 already disclose destructiveHint=true and openWorldHint=true, so the safety profile is partially covered. The description adds domain context and clarifies the sign-up slot concept, but it does not disclose persistence effects, permissions, return behavior, or how appointment creation interacts with existing scheduling data. No contradiction with annotations was found.

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 focused sentences with zero filler. The description front-loads the action and audience, and quickly guides required inputs. It earns its space without redundancy.

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

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

Given 11 parameters, 2 enums, and no output schema, the description covers the core workflow adequately by naming the required parameters and example slot format. It could have explicitly stated what the API returns or directed users to update_appointment_group for changes, but the existing schema and sibling names fill most of the gap.

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 each parameter already has a meaningful description, including new_appointments as [start_at, end_at] pairs. The tool description reinforces these points but doesn't materially add beyond the schema—it just restates the requirement for at least one context_code, a title, and the new_appointments format.

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 appointment group (sign-up slots) in Canvas Scheduler.' This clearly identifies the action and object, and distinguishes it from sibling tools like update_appointment_group, get_appointment_group, and list_appointment_groups.

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 implies when to use it — when creating a new appointment group — but does not explicitly compare it with alternatives such as update_appointment_group for modifying existing groups. There are no when/when-not statements, so usage remains implied rather than explicit.

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 says 'Create a new assignment,' implying an additive, non-destructive operation, but annotations mark destructiveHint: true. This is a direct contradiction: creating a new assignment should not be flagged as destructive. The description also adds no behavioral context beyond the raw action.

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

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

The description is a single efficient sentence with no wasted words and the core purpose is front-loaded. It is concise, though it sacrifices useful context that could have been included without bloating the text.

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?

Although the schema is complete and no output schema is required, the description lacks necessary context about behavior, return values, and the conflicting destructive annotation. For a mutation/create tool, the description should at least clarify whether it overwrites, publishes, or interacts with existing course data; it does none of this.

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 fully documents all 7 parameters, including required fields course_id and name. The description adds no parameter-level meaning beyond the schema, which is the expected baseline at this coverage level.

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 uses a specific verb and resource: 'Create a new assignment in a course.' It clearly distinguishes this tool from siblings like create_new_quiz, create_course, and update_assignment by naming the assignment resource and the course context.

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 explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The intended use is only implied by the word 'create' and the resource name, with no comparison to related assignment tools like update_assignment or create_new_quiz.

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, the description discloses important behavior: exactly one target type is required, at least one date must be provided, omitted dates remain unchanged, duplicate student-set overrides return 422, and pseudonym resolution may be required. No statement contradicts the 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?

Every sentence earns its place: purpose, target constraints, date behavior, format requirements, duplicate-error warning, audit suggestion, and pseudonym precondition. The most important selection criteria are front-loaded, and 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?

For a mutation tool with 9 parameters, no output schema, and only openWorld/destructive hints, the description covers the critical selection rules, error conditions, and preconditions. The only notable gap is that it does not describe what a successful response contains, which would help an agent confirm the override was created and inspect the resulting object.

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

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

The schema already documents all 9 parameters with 100% coverage, so the baseline is 3. The description adds valuable parameter-level meaning: ISO 8601 format, the requirement to provide exactly one of student_ids/course_section_id/group_id, at least one date field, and the distinction between omitted dates and null values. This meaningfully exceeds the schema alone.

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

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

The description opens with a specific verb and resource: "Create a due-date / availability override for a specific assignment." It also clarifies the possible target scopes and explicitly references list_assignment_overrides, making it clear this is the create operation rather than a read or update operation.

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 strong when-to-use guidance: audit existing overrides with list_assignment_overrides first, resolve pseudonyms when CANVAS_PSEUDONYMIZE_STUDENTS is enabled, and provide real Canvas user IDs. It does not explicitly compare itself to set_student_assignment_dates or other assignment-related tools, but the audit and precondition guidance is clear and actionable.

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 says 'create' which is additive, but annotations declare destructiveHint: true, suggesting the tool may have destructive effects. This is a direct contradiction. The description adds no further behavioral context beyond this conflict.

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?

One sentence, front-loaded with the verb and resource. No wasted words.

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?

While the schema covers parameters fully, the description lacks any context about side effects or return behavior, and the destructiveHint contradiction creates confusion. For a simple create operation, a one-liner could suffice, but the annotation conflict makes it incomplete.

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?

All 6 parameters have descriptions in the schema, so the description does not need to compensate. The description adds no additional parameter semantics beyond the schema's full coverage.

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

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

The description clearly states the action (create), the resource (calendar event), and the platform (Canvas). It distinguishes from sibling tools like update_calendar_event and list_calendar_events by specifying 'new'.

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

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

The description provides no guidance on when to use this tool versus alternatives like update_calendar_event or list_calendar_events, nor any exclusions or prerequisites.

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 important behavioral context beyond the annotations: the export runs asynchronously, the tool returns an ID and initial workflow_state, and the link is time-limited. It doesn't contradict annotations, and it explains the asynchronous lifecycle.

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, front-loaded with the purpose, followed by the essential asynchronous behavior and a clear pointer to the polling tool. Every word is useful and no redundancy exists.

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 create operation with two parameters and no output schema, the description fully explains the workflow: start export, get ID and state, poll with get_content_export, and eventually retrieve a time-limited link. It is complete for agent selection and 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?

The schema already describes both parameters with 100% coverage, including the enum values for export_type and their meanings. The description only repeats the format names ('Common Cartridge / QTI / zip') without adding new semantic information, so it meets the baseline but adds no extra value.

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 uses a specific verb ('Start') and identifies the exact resource ('Canvas course content export') plus the valid formats (Common Cartridge / QTI / zip). It clearly distinguishes this from the sibling get_content_export, which is for polling progress.

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: the tool is for starting an export, and the description explicitly instructs to call get_content_export to poll progress and get the download link. It doesn't mention when to choose this over content migration tools, but the primary workflow is well covered.

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 discloses asynchronous behavior: the tool returns immediately with a migration ID and a progress_url, and explicitly directs polling get_content_migration or progress_url for completion. The annotations include openWorldHint=true, meaning the operation may have side effects outside the system. The description notes the user can select content for selective import via get_migration_selective_data when selective_import is true, adding important behavioral context. However, it doesn't explicitly address that the operation is long-running or potentially destructive—although the destructiveHint=true annotation is consistent with a function that copies data into a course, so there's no contradiction.

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 main verb and resource. The first sentence lists specific migration types, the second explains asynchronous behavior, and the third tells the agent exactly what to do next—check get_content_migration or progress_url. No wasted words.

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 tool with 5 parameters, no output schema, and no explicit output schema, the description explains the asynchronous return (migration ID and progress_url), tells how to track completion (poll get_content_migration or progress_url), and mentions the selective import flow (get_migration_selective_data). It also packages the key mental model of destination course_id. The description makes the tool fully usable without additional lookups.

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 doesn't need to repeat parameter details. However, the description makes an important semantic clarification that the tool initiates a migration, frames the course_id as the destination course, and explicitly mentions 'poll get_content_migration or progress_url to track completion,' connecting the returned ID to the broader workflow. While the description doesn't add function-call details for each parameter, it clarifies the asynchronous workflow.

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 title and description clearly state the tool starts a content migration with a specific verb. The description says 'Start a content migration' and lists the migration types (course copy, Common Cartridge import, zip import, QTI conversion, or Moodle conversion), which uniquely identifies this tool even among migration-adjacent siblings like create_content_export and list_content_migrations. The phrase 'course copy' in the description maps to the sibling get_content_migration, providing clear differentiation.

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 indicates this is an asynchronous action ('Migrations are asynchronous — this tool returns immediately with a migration ID and progress_url'), which guides the agent on expected behavior. It also names the related tool get_content_migration for tracking completion. However, there is no explicit 'when not to use' guidance contrasting it with alternatives like create_content_export or upload_file, though the clear subject matter partially covers this.

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 signal mutation via destructiveHint=true, and the description adds the useful detail that the created course object is returned. However, it does not disclose potential side effects, permission requirements, or failure behavior; the added behavioral context is minimal but not contradictory.

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

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

The description is a single, front-loaded sentence with no filler. The return-value statement earns its place and the entire description is efficiently structured.

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 create operation with five params fully described in the schema, the description is mostly complete: it states the action, the target context, and the return value. It lacks usage differentiation and deeper side-effect context, but nothing critical is missing for basic invocation.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline score 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 uses a specific verb and resource ('Create a new course in a Canvas account') and identifies the action clearly. It does not explicitly differentiate from sibling tools like update_course, but the word 'new' and the creation-oriented phrasing make the purpose reasonably distinct.

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 guidance on when to use this tool versus alternatives such as update_course or create_module. There are no conditions, exclusions, or references to sibling tools, leaving usage context entirely 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?

The description adds no behavioral detail beyond what annotations already indicate. Although destructiveHint=true and openWorldHint=true signal mutation and potentially unexpected side effects, the description itself does not explain what changes occur, whether publishing is automatic, or how announcement requests behave. It does not contradict the annotations, but it also contributes no transparency value.

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

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

The description is a single, front-loaded sentence with no filler or redundant wording. It states the core purpose efficiently, which is exactly what a concise tool description should do.

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?

The schema thoroughly documents parameters, but the overall description lacks important contextual details for a complex create operation: expected return value, publishing defaults, permission implications, and clarification that this is a write/destructive action. The annotations cover some safety context, but the description alone remains minimal for an 8-parameter tool with no 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?

All 8 parameters have rich descriptions in the input schema, including nuanced details like the is_announcement downgrade behavior and ISO 8601 datetime format. With 100% schema coverage, the description does not need to restate parameter meaning. 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?

The description clearly states a specific action ('Create'), a specific resource ('new discussion topic'), and scope ('in a course'). It distinguishes itself from discussion-related siblings by focusing on creation, but it does not explicitly differentiate from alternatives like post_discussion_entry or update_discussion.

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: use this when you want to create a new discussion topic. However, there is no explicit guidance about when not to use this tool or when a sibling like post_discussion_entry or update_discussion would be more appropriate.

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 include destructiveHint: true but the description doesn't elaborate on the destructive aspect beyond implying creation. It does mention the POST key and response key difference, which is useful. However, it doesn't state side effects like whether it replaces an existing standard or if there are limitations. Given the annotation, some credit for adding request/response key nuance, but no behavioral details about side effects or irreversibility.

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?

Single paragraph, information-dense, front-loaded with purpose, then context, then parameter semantics, then return usage. No fluff, every sentence provides unique value.

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

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

Given the tool complexity (4 params, one nested object), the description covers purpose, input requirements, sorting, API key naming nuance, and how to use the returned id. It's missing some details like whether the returned object format is fully described (no output schema), but it gives enough to proceed. With annotations (openWorldHint, destructiveHint) and 100% schema coverage, it's reasonably 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 coverage is 100% (all parameters have descriptions), but the description adds value: explains the value fraction meaning, sorting behavior, and the lower-bound concept. This goes beyond schema text (e.g., schema doesn't mention sorting or that lowest grade should be 0.0). Since coverage is high, baseline is 3, and this adds significant extra meaning, so 4 is justified.

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?

Clearly states 'Create a new grading standard' with specific context (course/account), and the description adds important details like the scheme_entries format and sorting behavior, distinguishing this from sibling tools like list_grading_standards or apply_grading_standard_to_course.

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 explains when to use it (create) and how it relates to activation ('use that id with apply_grading_standard_to_course'), plus clarifies the mutually exclusive course_id/account_id choice and admin requirement for accounts.

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 is minimal and does not disclose side effects or potential destructive nature. The annotation 'destructiveHint: true' contradicts the create operation, creating confusion. The description adds no additional behavioral transparency beyond the contradictory annotation.

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

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

The description is a single, concise sentence with no redundant information. It perfectly fits the purpose without fluff.

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 simplicity of a create operation, the description is adequate but lacks mention of return values or error behavior. Additionally, the contradictory annotation reduces the overall completeness, as the description does not resolve the ambiguity.

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?

All 5 parameters are documented in the schema with brief descriptions, achieving 100% coverage. The description itself adds no extra nuance or clarification beyond the schema, so it meets the baseline score of 3.

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

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

The description clearly states the action (create a new module) and the resource (module in a course). It is distinct from other create tools like create_course or create_assignment based on the verb and resource, though it doesn't explicitly compare to 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?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or context for calling it. The use case is implied by the tool name but not explicitly 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?

While annotations provide openWorldHint and destructiveHint, the description does not add any behavioral context beyond the obvious creation action. It fails to mention that certain types require content_id, that adding items may affect module ordering, or any error conditions. With annotations present, the description's value is minimal, and it does not deepen the agent's understanding of side effects.

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

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

The description is a single, concise sentence that lists the item types. It is efficient and front-loaded, but slightly terse; a bit more detail on usage or parameter dependencies could enhance clarity without becoming verbose.

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

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

Given the tool's complexity (7 parameters, 8 item types), the description is overly minimal. It does not explain the relationship between type and content_id/external_url, nor does it address potential conflicts or prerequisites. The schema covers parameter details, but the description lacks sufficient context for an agent to confidently select and invoke the tool 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?

Schema coverage is 100%, so the descriptions in the schema already document all parameters. The tool description does not add any additional meaning or clarify relationships (e.g., content_id is required for specific types) beyond what the schema provides. This is the baseline for high coverage.

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

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

The description clearly states the action (Add) and the resource (item to a module), and lists the allowed item types, which distinguishes it from create_module (which creates a module itself). The verb and resource are specific and 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 implies usage (adding items to existing modules) but provides no explicit guidance on when to use this tool versus alternatives like create_assignment or create_page. There is no mention of when not to use it or prerequisites, leaving the agent to infer based on context.

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 signal destructiveHint, and the description confirms this is a create/mutating operation, so there is no contradiction. However, the description adds only the 'LTI' and 'modern quiz engine' context, not deeper behavioral details like permissions, draft/published defaults, or whether existing data is affected. With annotations present, this is acceptable but not richly transparent.

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 no filler: the first states the action and scope, the second provides the critical sibling distinction. The information is front-loaded 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 create tool with a fully described schema and safety-relevant annotations, the description is mostly complete. It explains what is created and how it differs from Classic quizzes. It does not mention return values or permissions, but the schema and annotations cover most invocation needs.

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 all eight parameters, including required fields and semantics. The description itself adds no parameter-level detail, so the baseline score 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: 'Create a New Quiz (LTI) in a Canvas course.' It also distinguishes this tool from Classic quizzes by naming create_quiz, making it easy for an agent to select the correct tool even among many 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?

The description explicitly says 'New Quizzes is the modern quiz engine; for Classic quizzes use create_quiz.' This gives a clear when-to-use and identifies the alternative, leaving little 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 signal mutation via destructiveHint=true, and the description adds non-obvious behavior: rate-limiting risks and the need for serial execution. It does not cover permissions or return values, but the annotation plus rate-limit context is solid.

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 with front-loaded purpose and no filler. Each sentence earns its place: what it does, what types it supports, and how to call it safely.

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?

The tool has a complex nested item schema and no output schema, but the description covers type support and batching guidance. It could mention return behavior or per-type requirements, but the schema handles most invocation details; a small gap around response/return value prevents a 5.

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 80%, and the schema already documents course_id, assignment_id, points_possible, position, and nested item fields. The description names the five item types but adds little beyond what the schema provides, so it meets the baseline without enriching parameter semantics.

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 an item (question) in a New Quiz (LTI)' and enumerates the five supported question types. It clearly distinguishes this from sibling tools like create_new_quiz, update_new_quiz_item, and get_new_quiz_item.

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 operational guidance: Canvas may rate-limit, call serially, chunk and pause for batches over 50. It does not explicitly name alternatives, but the creation scope and batching context give strong practical usage direction.

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 agent knows that this is not a read-only, fully predictable operation. The description adds no further behavioral context such as whether creation overwrites an existing page by title, how publishing defaults work, or what permissions are required. It merely re-states the create action without enriching the 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?

The description is a single, focused sentence with no filler. It front-loads the verb and object and states the course scope without adding redundant detail.

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?

The output schema exists so return values do not need to be explained, and the input schema already documents all parameters fully. The description would ideally offer a note about page title collisions or publishing defaults, but for a basic CRUD tool this remains sufficient for many an agent to invoke 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 input schema covers all 5 parameters with descriptions, including the HTML body, publisher, and editing roles, so the schema already carries the parameter load. The description does not add anything beyond the natural notion that the page belongs to a course, which was move the schema 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?

The description uses a specific verb ('Create') and resource ('new wiki page in a course'), making the primary action immediately recognizable. It also distinguishes this tool from siblings like update_page, delete_page, and get_page, which an agent could otherwise confuse with it by name alone.

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 word 'new' implicitly signals that this is for creating pages rather than updating existing ones, so some usage context is present. However, there is no explicit guidance about when to prefer this over update_page, nor mention of any exclusions or preconditions.

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 include destructiveHint=true and openWorldHint=true, so the agent knows the operation may have destructive/external effects. However, the description adds no extra context about what gets destroyed, permissions, reversibility, or side effects. It merely restates the action without elaborating on the noted destructive behavior.

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

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

The description is a single, concise sentence that states the action directly. It is front-loaded and contains no wasted words.

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 4-parameter assignment tool with full schema coverage and annotations, the description is sufficiently complete. It lacks explicit guidance on edge cases (e.g., overwriting existing peer reviews), but the simplicity of the tool and rich annotations make it adequate.

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 input schema covers all four parameters with descriptions, so the schema fully documents them. The description adds nothing beyond the schema, so a baseline of 3 is appropriate given 100% schema description coverage.

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 uses a specific verb+resource: 'Assign a user to peer-review a submission.' It clearly distinguishes from sibling tools that list or delete peer reviews (list_peer_reviews, delete_peer_review).

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

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

The description provides clear context for when to use: when a user needs to be assigned as a reviewer. It does not explicitly mention alternatives or exclusions, but the verb 'assign' differentiates from list/delete siblings, and the context 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?

With annotations (openWorldHint and destructiveHint), the description does not add significant behavioral context beyond what is implied by 'create'. It does not mention permissions, side effects, or error handling. The destructiveHint is present but unexplained, and the description does not clarify what happens on creation or if it overwrites anything. Minimal value added 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?

The description is two short sentences with no fluff. It front-loads the verb and resource, then adds the optional association. Every word earns its place, and it is appropriately sized for the tool's complexity.

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?

The tool has nested objects and no output schema, so the description should explain what is returned or any important side effects. It does not mention return values, error conditions, or prerequisites beyond the parameters. Given the complexity, the description is too minimal to be 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%, so the schema fully documents all parameters and nested properties. The description merely restates 'criteria and rating levels' and mentions the optional association, which does not add substantial meaning beyond the schema. Baseline score 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 clearly states the verb (create), the resource (rubric), the context (in a course), and the key components (criteria and rating levels). It also mentions an optional association, distinguishing it from sibling tools like get_rubric or list_rubrics which are read-only.

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

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

The description provides clear context for when to use it (to create a new rubric) and mentions the optional linking to an assignment, implying it can be used for that purpose. However, it does not explicitly exclude alternatives or mention when not to use it, so it lacks explicit exclusion but has clear context.

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 discloses the destructive nature (delete group) and additional side effects: cancelling reservations and notifying participants via cancel_reason. This goes beyond the annotation destructiveHint:true by specifying what is affected and the notification behavior, making it fully transparent.

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 concise, consisting of two short sentences. It is front-loaded with the primary action and provides necessary detail without any fluff or redundancy. The structure is clear and easy to parse.

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 delete operation with two parameters, the description is complete enough. It explains the main action and the effect of the optional parameter. It does not mention error handling or return values, but with no output schema and a straightforward destructive action, the description covers the essential context needed for an agent.

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 description explains the purpose of cancel_reason (to notify participants), adding meaning beyond the schema's generic 'Message to include in cancellation notifications.' The appointment_group_id is self-explanatory and not further elaborated, but the description does provide useful context for the optional parameter, improving parameter understanding.

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

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

The description clearly states the action: delete an appointment group and cancel existing reservations. It uses specific verbs (delete, cancel) and specifies the resource (appointment group), distinguishing it from other appointment group tools like get, create, update, and list.

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 does not explicitly state when to use this tool versus alternatives. The usage is implied: you use it to delete an appointment group. It does not mention conditions or exclusions, but the action itself is straightforward. The optional cancel_reason for notifications is noted, but no guidance on when to provide it is given.

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 destructive nature is covered. The description adds 'This action is permanent,' reinforcing the consequence, but does not disclose cascade effects on submissions/grades or any auth requirements.

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 resource, followed by the key consequence. Every word earns its place with no filler or repetition.

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 delete operation with strong annotations and full schema coverage, the description is sufficient. It states the action, the target, and the permanence; the absence of an output schema is acceptable for a delete 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?

The input schema documents both parameters with 100% coverage, so the description need not add parameter details. The description's mention of 'an assignment' and 'a course' aligns with the schema but adds no new semantic information beyond it.

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 uses a specific verb ('Delete') with a clear resource ('an assignment') and scope ('from a course'), making the purpose unmistakable. It also distinguishes the tool from siblings like create_assignment, update_assignment, and list_assignments.

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 implies when to use the tool: when an assignment should be removed from a course. However, it offers no explicit guidance about when not to use it or alternatives (e.g., update_assignment for edits instead of 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?

Annotations already set destructiveHint=true, and the description adds the valuable behavioral detail that the action is permanent, which is not fully captured by the annotation. It goes beyond the structured metadata by emphasizing irreversibility.

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 two short sentences that are front-loaded with the primary action and followed by a critical caveat. Every word earns its place; no filler or unnecessary detail.

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 delete operation with destructiveHint annotation and full parameter schema, the description provides the essential purpose and permanence caveat. There is no output schema to document, and no additional behavioral complexity requiring explanation.

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 input schema already provides full descriptions for both parameters (course_id and topic_id) with 100% coverage. The description itself adds no parameter-specific meaning, 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 uses a specific verb ('Delete') and resource ('discussion topic from a course'), clearly distinguishing it from sibling tools like create_discussion, update_discussion, and get_discussion. The scope is precisely stated.

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 context is implied by the clear delete action, but there is no explicit guidance on when to choose this tool over alternatives or any exclusions. For instance, it doesn't mention that this is only for discussion topics, not announcements. The permanence note indirectly warns of caution.

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, so the description's 'permanent' adds minimal new information. It does not disclose any additional behavioral traits beyond what annotations cover, such as side effects or authorizations required.

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 no filler. The purpose and key warning are front-loaded and concise.

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 deletion tool with one parameter and destructive annotation, the description is adequate. It omits potential side effects (e.g., cascading deletion of associated objects) but is acceptable given the simplicity and annotation coverage.

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% with the sole parameter file_id described as 'The Canvas file ID'. The description adds no extra meaning beyond the schema's parameter documentation, so 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 description clearly states 'Delete a file by ID', using a specific verb and resource. It distinguishes from sibling tools like upload_file, download_file, and get_file by focusing on the deletion action.

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 implies usage (when you want to permanently delete a file) but does not explicitly mention alternatives or when not to use it. It could benefit from noting that the action is irreversible, but that is also implied by annotations.

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 the description adds the valuable explicit detail that 'This action is permanent.' It also clarifies the LTI-specific nature of the New Quiz object and the assignment_id requirement, giving the agent context beyond the raw destructive 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 short sentences, front-loaded with the primary action, with no filler. Every sentence contributes: resource/scope, permanence, and a critical identifier 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 delete with no output schema and strong annotations, the description covers the important operational facts (permanence and assignment_id). It is complete enough for the agent to invoke correctly, though it could have explicitly named sibling alternatives for fully unambiguous selection.

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

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

The schema already documents both parameters with 100% coverage. The description adds meaningful clarification with 'Use assignment_id (not quiz_id),' which prevents a likely misuse when deleting New Quizzes; course_id semantics are adequately handled by 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?

Description opens with a specific action and object: 'Delete a New Quiz (LTI) from a Canvas course.' It also clarifies the correct identifier type ('Use assignment_id (not quiz_id)'), which distinguishes this deletion tool from quiz-item or classic-quiz deletion tools.

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 clearly scopes the tool to New Quiz (LTI) objects in a Canvas course, and the assignment_id note implies this is not the normal quiz_id-based path. However, it does not explicitly name alternatives (e.g., delete_assignment for regular assignments or delete_new_quiz_item for quiz items), so when-to-use versus siblings is only implied.

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 explicitly states 'This action is permanent,' which is crucial behavioral information beyond the annotations (destructiveHint=true, idempotentHint=true). It adds context that deletions are irreversible. It does not mention auth requirements or side effects on quiz structure, but the permanence is a strong plus.

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 two sentences, both essential: the first defines purpose and scope, the second adds critical behavioral context. No wasted words.

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 destructive nature and the annotations, the description is quite complete. It notes permanence, which many destructive operations lack. It could mention prerequisites (like existence of the quiz) but the schema already requires all IDs, and the output is likely void. Overall adequate for the tool's complexity.

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

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

Schema coverage is 100%, documenting all three parameters. The description does not add parameter-level details, but the schema is sufficient. The description's 'permanent' note complements the parameter semantics by emphasizing the irreversible nature, which is valuable context.

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

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

The description clearly states the action ('Delete an item (question)') and the resource ('a New Quiz (LTI)'), distinguishing it from siblings like delete_new_quiz (which deletes the quiz itself) and get_new_quiz_item. It is specific and concise.

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 does not explicitly state when to use this tool versus alternatives (e.g., delete_new_quiz_item vs delete_new_quiz). The context implies it's for deleting individual questions within a New Quiz, but no explicit guidance on when not to use it or alternative tools is provided.

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 the specific note that the action is permanent, which goes beyond the destructiveHint annotation by emphasizing the irreversibility. It doesn't detail other side effects, but for a delete operation, this is sufficient 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 extremely concise, consisting of two short sentences with no redundancy or unnecessary detail. It is well-structured and directly conveys the essential 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 simple delete operation, the description fully covers the necessary context: what is being deleted, from where, and that it is permanent. No additional explanation is required, and the output schema is not needed to clarify the action.

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

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

The schema already provides descriptions for both parameters (page_url and course_id), covering 100% of them. The tool description does not add any additional meaning or clarification about these parameters, so the baseline score 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 clear verb ('delete'), the resource ('wiki page'), and the scope ('from a course'), and explicitly notes that the action is permanent, leaving no ambiguity about what the tool does.

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 does not explicitly mention alternatives like 'edit' or 'create', but the permanence warning implies caution. Given the straightforward nature of a delete operation and the surrounding tool list, the usage context is clear enough.

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 'This action is permanent,' which is beyond the destructiveHint annotation, but it does not elaborate on other behavioral aspects like side effects, reversibility, or authorization requirements. Given the annotation already flags destructiveness, the added permanence is useful but limited.

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 two short sentences, front-loaded with the action and the key constraint (permanence). Every word earns its place; there is no fluff or redundancy.

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

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

For a simple delete operation with full schema coverage and destructive annotations, the description is adequate but minimal. It does not mention potential failure conditions, effects on related data, or required permissions, but these are not strictly necessary given the simple operation and 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?

All four parameters are fully described in the schema (100% coverage), so the description does not need to explain them further. It adds no extra meaning beyond the schema, which is adequate as a 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?

The description uses a specific verb ('Remove') and clearly identifies the resource ('a peer review assignment from a submission'). It is distinct from sibling tools like create_peer_review and list_peer_reviews, making its purpose 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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, conditions, or when not to use it. The description merely states what it does, leaving the agent to infer usage context.

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 goes beyond the read-only annotation by explaining how text files are returned as readable text, binary files as base64, and that files over 10 MB are refused. These are important behavioral details not covered by 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?

The description is concise, with the main purpose stated first, followed by file type handling and size limit. It is well-structured and easy to read without unnecessary verbosity.

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?

The description covers the core functionality, return types, and size constraint. It lacks details on error cases (e.g., file not found), but for a simple download tool, this is fairly complete. No output schema exists, so the return behavior description suffices.

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

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

The schema already provides clear descriptions for file_id and course_id. The description adds little extra meaning, mostly repeating 'by ID'. Since schema coverage is 100%, 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 clearly states that the tool downloads the content of a Canvas file by ID. It distinguishes itself from sibling tools that list or get file metadata by focusing on content retrieval.

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 does not explicitly mention when to use this tool over alternatives like get_file or list_files. It implies usage for downloading actual file content, but lacks explicit guidance or examples.

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 no context about potential side effects (e.g., overriding existing enrollments, changing user access). The description only states the basic action, leaving the agent without behavioral insights beyond the annotation.

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

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

The description is a single sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and efficient.

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?

The tool has four parameters and no output schema, and the description is minimal. It does not mention default behavior like enrollment_state defaulting to 'invited', potential conflicts with existing enrollments, or the meaning of the destructiveHint annotation. Adequate for a simple operation but with clear gaps.

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%, with all parameters described in the input schema. The description's mention of 'specified role' reinforces the `type` parameter but adds no additional meaning beyond what the schema already provides, so 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 'Enroll a user in a course with a specified role' clearly identifies the action (enroll), the resource (user in course), and the key parameter (role). It distinguishes this from sibling tools like remove_enrollment and list_enrollments.

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 implies its usage by stating the output action, but it does not explicitly say when to use it versus alternatives like remove_enrollment or list_course_enrollments. No exclusions or prerequisites are mentioned.

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 behavioral context beyond the readOnlyHint/openWorldHint annotations: it discloses that Canvas REST API does not expose curves/fudge points, that a caveat is added for discrepancies over 0.5 pp, that only one student is computed per call, and that reconciliation is against the cross-period grade under grading periods. This goes well beyond the structured 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?

The description is structured with a dense first sentence followed by a focused limitations list. Every sentence adds relevant information—calculation details, use case, student constraint, API limitation, grading-period handling, and pseudonym prerequisite. No filler or redundancy.

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

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

Despite lacking an output schema, the description thoroughly conveys what the tool computes and what caveats apply. It covers the calculation inputs, the reconciliation behavior, limitations due to API gaps, grading periods, and pseudonymization. This is sufficient for an agent to decide when and how to invoke the tool 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?

Schema coverage is 100%, so the baseline is 3, but the description adds useful extra semantics: 'V1 computes one student per call' clarifies the student_id limitation, and the pseudonym-resolution note adds operational behavior around the parameter. The assignment_group_id narrowing behavior is already fully described in the schema, so the description's additional value is moderate but meaningful.

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

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

The description opens with a specific verb and resource: 'Recomputes and explains the weighted course grade for a student.' It enumerates the exact outputs (assignment-group weights, drop rules, per-group breakdowns, letter grade, reconciliation check), clearly distinguishing this from generic grading or policy tools like project_grade and explain_grading_policy.

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 states when to use the tool: 'Use this when you need to verify that Canvas's displayed grade matches the rules, or to explain to a student or instructor how their grade was calculated.' It also provides important prerequisites and limitations (one student per call, pseudonym resolution, grading-period caveat), though it does not explicitly name alternatives or say when not to use it.

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 and destructiveHint=false, so the read-only nature is known. The description adds valuable behavioral context: it returns sections depending on permissions, includes a caveat for students, and provides a shareable summary paragraph. This goes beyond the annotations by explaining what different users see and the permission dependency, making it highly transparent.

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

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

The description is well-structured with bullet points for each policy area and a concluding note about alternatives and permissions. It is concise—no redundant sentences—and front-loaded with the main purpose. Every sentence adds relevant 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?

The tool explains multiple aspects of grading policy, and the description covers all major return sections (missing/late policies, weights, scheme) as well as the summary paragraph. Since there is no output schema, the description effectively replaces that by outlining what the agent can expect. Permission differences and alternative tool are also covered, making it complete for a tool of this complexity.

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 only parameter, course_id, is fully described in the schema ('Canvas course ID to explain the grading policy for'). Schema coverage is 100%, so per the rubric the baseline is 3. The description does not add additional parameter semantics, but the schema is sufficient; no further clarification is needed.

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

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

The description clearly states that the tool 'Explains the grading automation rules configured for a Canvas course' and enumerates specific aspects (missing-submission, late-submission, group weighting, grading scheme). It distinguishes itself from sibling explain_grade by explicitly mentioning that compute actual weighted grade is a different tool, so the purpose is specific and 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 note explicitly says 'Use explain_grade to compute the actual weighted grade for a specific student,' providing a direct alternative. It also explains permission requirements (instructor/admin for late/missing policy, students get limited sections), giving clear guidance on when and for whom this tool is appropriate.

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 and openWorldHint=true, so the description doesn't need to repeat that. It adds useful behavioral context: grouping by display name + size, noting that Canvas lacks content hashes, and that same-name files of different sizes are not considered duplicates. This goes beyond the 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?

The description is concise and front-loaded with the core purpose. Every sentence adds value: the purpose, the rationale, the grouping logic, and the limitation. No wasted words.

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

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

Given the tool's simplicity (2 params, no output schema), the description is complete. It explains the detection criteria, the limitation regarding content hashes, and the intended use case. The only minor gap is not describing the return format, but with no output schema and a straightforward list result, this is acceptable.

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 both parameters. The description adds context about the grouping logic but doesn't add new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds duplicate files in a course's Files area, specifying the criteria (same name and size) and the context (left behind by repeated course copies). It distinguishes itself from sibling tools like list_files and delete_file by focusing on detection of duplicates for cleanup.

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 when to use this tool (to surface duplicates for cleanup) and mentions the alternative delete_file tool for the actual deletion. It doesn't explicitly state when not to use it, but the context is clear enough for an agent to decide.

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 (readOnlyHint: true, openWorldHint: true) are supplemented by rich behavioral details: concluded courses are included by default, max_courses bounds scanning with most-recent-term-first ordering, truncated is set rather than silently dropping courses, and failed courses are skipped and listed in courses_failed. This goes far beyond the structured 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?

Three dense, purposeful sentences. Each sentence delivers distinct value: scope and outcome, parameter options, and edge-case handling. No filler or repetition, and the main action is front-loaded.

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 no output schema, the description adequately explains the return concept (every matching course with enrollment state and last activity) and covers important behaviors (truncation, failed courses, defaults). The tool's complexity is moderate, and the description leaves no major gaps for an agent to invoke it 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?

Schema coverage is 100% for the three parameters, and the description adds meaningful semantics beyond the schema: default values for include_concluded and max_courses, the ordering (most recent term first), truncation flag behavior, and per-course error reporting. This substantially enhances parameter understanding.

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?

Description states a specific verb ('Search') and resource ('the caller's teaching courses'), and includes scope (active and concluded) plus result details (enrollment state, last activity). This clearly distinguishes it from sibling tools like search_users or list_students, which operate on different scopes.

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 on when to use this tool: to find a student by name/login/email across the caller's teaching courses, with defaults and flags (include_concluded, max_courses). However, it does not explicitly name alternative tools or state when not to use it, so it falls short of the 'explicit when/when-not/alternatives' level.

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 readOnlyHint: true, so the description's 'Get details' is consistent and adds no new safety information. It does not describe return format, error behavior, or any side effects beyond the read-only nature, which is already covered by the annotation.

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

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

The description is a single concise sentence that immediately conveys the tool's purpose. Every word earns its place, with no wasted or redundant phrasing.

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

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

Given the tool's simplicity (one parameter, no output schema, read-only annotations), the description is complete enough. It tells the agent exactly what the tool does and how to use it, and the structured fields handle the rest.

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 input schema has 100% coverage with the parameter description 'The Canvas account ID', so the description adds no additional meaning beyond the schema. This is the baseline for high schema coverage, and no extra semantic detail is provided.

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 uses a specific verb 'Get', names the resource 'Canvas account', and includes the scope 'by ID', making it clear that this retrieves a single account rather than listing accounts. It effectively distinguishes itself from sibling tools like list_accounts or list_sub_accounts by implying a specific lookup.

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

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

The description provides clear context that this tool is for retrieving a specific account by ID, which implicitly indicates when to use it instead of listing tools. However, it does not explicitly name alternatives or give when-not-to-use guidance, so it falls slightly 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?

The annotations indicate read-only and open-world hints, and the description does not contradict them. However, it does not add any additional behavioral context such as side effects, error handling, or any constraints beyond listing report types.

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

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

The description is a single, clear sentence with no unnecessary words, making it highly concise and easy to understand.

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?

The description covers the core functionality but lacks details about the output format or any specific behavior. Given the simplicity of the tool and absence of output schema, it is adequate but not rich.

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 input schema already describes the account_id parameter with a description, so the tool description adds no extra meaning. The description only mentions 'a Canvas account' which is consistent but not additional.

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

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

The description clearly states that the tool lists available report types for a Canvas account, which is specific and distinguishable from other tools like list_accounts or get_account.

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

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

The description provides no guidance on when to use this tool versus alternatives, lacking any context about use cases, prerequisites, or conditions. It only states the action without explaining when it is appropriate.

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 and openWorldHint=true, so the description does not need to restate safety. However, the description's claim that the result 'including its time slots and participant counts' contradicts the schema where these are only included via the optional 'include' parameter. This misstatement misleads about default behavior, a notable gap given no additional behavioral details are provided.

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

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

The description is a single, front-loaded sentence that states the action, object, and key details without any filler words. Every word earns its place, and it is appropriately concise for a simple get-by-ID operation.

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

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

Given the tool's simplicity and strong schema coverage, the description is mostly sufficient, but the misleading 'including' statement omits the optional nature of the include parameter. There is no output schema, so a clearer indication of what the base response contains (absent include) would improve completeness. It also does not mention any prerequisites or error conditions, leaving some context gaps.

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

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

The schema already has 100% parameter coverage with clear descriptions for both 'include' and 'appointment_group_id'. The description adds minimal value beyond referencing 'time slots and participant counts', which are covered by the enum values. It does not clarify that these are optional or default behavior, so it neither enhances nor detracts significantly from 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?

The description clearly states the tool gets a single appointment group by ID, explicitly distinguishing it from listing all groups. The phrase 'including its time slots and participant counts' slightly misleads by implying these are always returned, but the core action 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 purpose implies use for retrieving a specific group, but there is no explicit guidance on when to use this versus sibling tools like list_appointment_groups or create/update/delete. No alternatives or exclusions are mentioned, so guidance is only implicit.

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 aligns with the readOnlyHint annotation and adds value by indicating that optional fields like submission, overrides, and all_dates are requested via include rather than returned by default. It doesn't reveal additional behavior such as response shape, error conditions, or rate limits, so it provides only partial transparency beyond the 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?

The description is two concise sentences with front-loaded purpose. Every word earns its place; no redundant or verbose phrasing.

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 read-only, single-resource retrieval nature and rich schema descriptions, the description is sufficient for an agent to call this tool correctly. The absence of an output schema is not a large gap because the tool name and 'get details' wording convey the expected return type, but the description could add a little more context about how actual include returns are shaped.

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 already have descriptions. The tool description reinforces the include parameter's usage but does not add new semantic details or clarify formatting, types, or relationships beyond what the schema already provides.

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

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

The description clearly states the action ('Get details') and the resource ('a single assignment by ID'), distinguishing it from list-oriented sibling tools like list_assignments and get_assignment_analytics. The mention of optional include fields adds further scope and purpose specificity.

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

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

The description explicitly positions this tool as the way to fetch details for a single assignment by ID and instructs the agent on how to request optional fields via include. It does not name alternative tools or provide explicit non-use cases, but the intent is clear.

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 and openWorldHint=true, so the read-only nature is established. The description adds valuable behavioral context by detailing what the tool returns (min, max, median, quartiles, submission count, tardiness breakdown), going beyond the structured 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?

The description is two concise sentences. The first establishes the core purpose and output, the second explains the optional parameter behavior. Every sentence earns its place with no redundancy.

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

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

Given there is no output schema, the description carries the burden of explaining return values and does so thoroughly: statistical summary fields, submission count, tardiness breakdown with categories. It also covers parameter scoping and reads as complete for the tool's complexity, supplemented by 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 the schema already fully documents both parameters. The description's guidance on assignment_id essentially mirrors the schema's own description ('Scope the result to a single assignment ID. Omit to return analytics for all assignments'), adding no new semantic information.

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

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

The description clearly states the tool's function: 'Get score distribution analytics for assignments in a course.' It lists specific outputs (statistical summary, submission count, tardiness breakdown) and distinguishes itself from sibling tools like get_course_analytics and get_student_analytics by focusing on assignment-level score distribution.

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

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

The description provides clear context on when to use the tool (for assignment score analytics) and how to scope it to a specific assignment via assignment_id, with an explicit 'omit to return analytics for all assignments.' However, it does not name alternative tools or state exclusions, so it misses the explicit '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?

Even though annotations already mark readOnlyHint=true and openWorldHint=true, the description adds valuable context: the work flow states, URL expiry and the need to re-fetch, and the null attachment behavior. This goes beyond the annotations and helps the agent understand transient behavior.

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 concise, two sentences, with the core purpose front-loaded. It efficiently covers the essential behavior without unnecessary verbosity.

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 status-checking tool, the description fully covers the relevant behavior: the states, the download link, expiry handling, and null attachment cases. With no output schema, the description explains what to expect, making it complete for the tool's complexity.

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%, with both parameters (course_id and export_id) fully described in the schema. The description adds no new parameter-level information; it only mentions the export ID's source, which is already in the schema. 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 clearly states 'Get the status of a content export' which specifies the verb and resource. It also distinguishes from siblings like list_content_exports (which lists exports) and create_content_export (which creates them) by focusing on a single export's status.

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 context is implied through the mention of 'export ID returned by create_content_export' in the schema, but the description doesn't explicitly state when to use this versus alternatives like list_content_exports. It doesn't specify preconditions or exclusions, so guidance is not explicit.

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 readOnlyHint and openWorldHint annotations, the description adds response-related behavior: progress_url polling and workflow_state transitions. It does not mention error/failed states or polling cadence, but the annotations already establish this as a safe read 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 is two sentences, front-loads the main purpose, and then provides actionable polling guidance. 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 simple single-item read with no output schema, the description covers the essential response behavior: workflow_state handling, progress_url, and completion. It could be more complete by enumerating other states such as 'failed' or specifying a polling interval, but it is sufficient for effective tool selection and invocation.

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

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

Schema description coverage is 100%, and both course_id and migration_id already have clear descriptions in the input schema. The tool description adds no parameter-level meaning, 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 uses a specific verb and resource: 'Get the status of a single content migration.' The word 'single' clearly distinguishes this from sibling tools like list_content_migrations and list_content_exports.

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: poll progress_url when workflow_state is 'running' and treat 'completed' as terminal. It does not explicitly name alternatives or state when not to use this tool, 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 and openWorldHint=true, so the agent knows this is a safe read operation. The description adds that it returns the full message thread, which is useful context, but doesn't disclose pagination, ordering, or any other behavioral details beyond what annotations provide.

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

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

The description is a single, efficient sentence with zero waste. It front-loads the purpose and includes the key detail about the full message thread.

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 read tool with one parameter, good annotations, and no output schema, the description is complete enough. It states what it returns (full message thread) and the parameter is fully documented in the schema. No significant gaps.

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% (conversation_id is described as 'The conversation ID'), so the schema already documents the parameter. The description doesn't add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a single conversation with its full message thread, using a specific verb ('get') and resource ('conversation'). It distinguishes from sibling tools like list_conversations and get_conversation_unread_count, though it doesn't explicitly name them.

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 implies usage for fetching a specific conversation by ID, but doesn't explicitly state when to use it versus alternatives like list_conversations or get_conversation_unread_count. No exclusions or alternative tool names are provided.

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 and openWorldHint=true, covering safety and mutability. The description adds the 'authenticated user' scope, which is useful, but does not elaborate on response shape or any other behavioral details. This matches the calibration example for get_calls.

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?

Single sentence, front-loaded, no redundancy. Every word contributes to the purpose.

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

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

For a zero-parameter read-only tool with annotations, the description suffices. It clearly states what is counted and for whom. It does not specify the output format, but a count implicitly returns a numeric value; however, mentioning this would have been slightly more 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?

With zero parameters, the baseline is 4 per rubric. The description adds context by specifying the count is for the authenticated user, which clarifies the implicit scope. No further parameter explanation is needed.

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: 'Get the number of unread conversations for the authenticated user.' It clearly distinguishes itself from siblings like list_conversations (which retrieves a list) and get_conversation (a single item) by focusing on a count.

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 purpose itself makes the usage clear: use this when you only need the unread count rather than the full list. However, it doesn't explicitly mention alternatives or when not to use it, which would be 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, and the description adds behavioral context by stating defaults (term, total_students) and that the include parameter replaces (not augments) the default set. This goes beyond the annotations without contradicting them, though it does not describe response structure or potential errors.

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, front-loaded with the primary purpose, followed by the default behavior and the key parameter behavior. No filler words; 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 read-only tool with all parameters documented in the schema and no output schema, the description covers the essential behaviors: what it does, what is returned by default, and how to customize. The teacher_limit parameter is adequately described in the schema, and the description's focus on include semantics fills the most nuanced gap. Overall, the tool is fully characterized for an agent to select and invoke 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 schema already documents all 3 parameters, but the description adds key semantics: it reveals that `term` and `total_students` are requested by default and that `include` replaces this default set, which is not evident from the schema alone. This meaningfully helps the agent use the include parameter correctly, especially with the enum list provided.

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

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

The description opens with 'Get details for a single course,' a specific verb+resource that clearly differentiates from siblings like list_courses and get_course_analytics. It also clarifies the single-course scope, which is further reinforced by the required course_id parameter in 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 indicates it operates on a single known course (implied by 'single course') and explains the default include set and how to replace it, but it does not explicitly specify when to use this tool over alternatives like list_courses or get_course_analytics. Thus usage guidance is implied rather than explicit, with no clear exclusions or named alternatives.

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

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

The readOnlyHint annotation already communicates no side effects, and the description adds that it returns counts by event type. However, it does not disclose potential limitations (e.g., date ranges, pagination, or error behavior) beyond the basic read-only nature, so it partially relies on the annotation.

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 brief, with two sentences that directly state the function and the return value. No unnecessary words or repetition; it is well-structured for a simple getter.

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?

The description explains the return value ('counts of recent events grouped by type') which is useful given there is no output schema. It provides enough context for a consumer to understand the tool's purpose and expected result, though it does not detail the exact response structure.

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 'course_id' is described in the schema as 'The Canvas course ID', which is clear and complete. The description does not add extra nuance, but given full schema coverage, the parameter semantics are well understood.

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

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

The description clearly states the action ('Get') and the resource ('a summary of recent activity in a course'), and it specifies the output type (counts grouped by type). This distinguishes it from other course-related tools like listing assignments or getting a specific assignment.

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 indicates what the tool does but does not specify when to use it compared to alternatives (e.g., checking individual activity or using a dashboard stream). It implies a high-level overview but lacks explicit guidance on scenarios or prerequisites.

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