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

Annotations provide destructiveHint and openWorldHint, and the description adds behavioral value by explaining that the operation affects the gradebook, that null removes the current grading standard, and that an updated course object is returned. It does not discuss recalculation side effects, but the destructive annotation covers the safety implication.

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 no filler. The purpose, parameter provenance, null handling, and return value each earn their place, 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?

For a simple two-parameter mutation with a rich schema and destructive annotation, the description is sufficient: it gives the ID source, removal behavior, and return type. Since no output schema exists, 'Returns the updated course object' is an appropriate concise contract.

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 meaning by telling the agent where grading_standard_id comes from and that null is a valid removal value. The course_id remains schema-only but is self-explanatory.

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 the verb 'apply', the resource 'an existing grading standard to a course', and the intended effect 'so the gradebook uses it.' This distinguishes it from sibling tools like create_grading_standard and list_grading_standards by focusing on the application step, not creation or 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?

Gives explicit usage context: the grading_standard_id should come from create_grading_standard or list_grading_standards, and null removes the current standard. It does not explicitly state when not to use the tool, but this is clear enough for an agent to select it correctly.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses the severity taxonomy (error vs advisory), the dependency on rendered theme CSS for the excluded color-contrast check, the opt-in default for quizzes, and the permission requirement. No contradiction with annotations — 'Scan' confirms the readOnlyHint=true safety profile.

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

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

Each of the six sentences earns its place: purpose, findings, severity, exclusions, opt-in behavior, alternative tool, permissions. It is front-loaded with verb and resource, but the single dense paragraph could be broken into scannable sections for faster agent parsing.

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?

Complete for a 2-param read-only tool: parameters are 100% schema-covered, annotations cover the safety profile, and because there is no output schema, the description compensates by stating that each finding carries a WCAG success criterion and severity. Permissions, limitations, and alternatives are all present.

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

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

Schema description coverage is 100%, and the include parameter's schema text already documents the default four sources and the quizzes opt-in, so the schema carries the load. The description reinforces the quizzes opt-in but adds no parameter meaning 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?

States a precise verb ('scan'), a specific resource (course content: pages, assignments, syllabus, announcements, optionally quizzes), and enumerates the exact problem classes detected (missing/low-quality alt text, non-descriptive links, duplicate links, heading issues, table issues). The scope delimiter 'structurally-detectable' plus named exclusions cleanly separate it from sibling auditing tools such as audit_course_links.

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 frames when NOT to use it: 'Complements — does not replace — Canvas's own in-app Accessibility Checker,' which covers rendered color contrast and offers in-UI remediation. It also states the prerequisite ('Requires instructor permissions in the course') and the structural-only boundary, so an agent can route color-contrast requests elsewhere.

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 annotation, the description discloses meaningful behavior: 'Structural checks only — no outbound HTTP requests,' the extra Canvas API call per quiz when quizzes are included, and the permission requirement. This gives an agent accurate cost, safety, and side-effect expectations beyond what annotations alone 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 dense but every sentence earns its place: scope, findings, opt-in behavior, justification, cost, constraint, and permission. It is front-loaded with the core action, then layers behavioral detail without padding.

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

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

For a two-parameter tool with rich annotations and no output schema, the description is complete: it covers default content, opt-in extension, permission requirements, operational cost, and the nature of returned findings. Nothing an agent needs to decide whether and how to call it is missing.

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

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

Input schema coverage is 100%, and the include parameter's schema description already explains defaults, opt-in behavior, and the extra API call. The main description adds context about why quiz scanning matters, but for parameter semantics specifically it mostly repeats schema content, so the high-coverage 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 opens with a specific verb and resource: 'Scan a course's content ... for broken or outdated links and images.' It further distinguishes the tool by naming the exact findings it produces (cross-course references, empty/malformed URLs) and the content sources it covers, which separates it from nearby audit/search 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?

It clearly states when to include quizzes (opt-in, because they 'break silently for students'), the default set of scanned content, and the permission requirement ('Requires instructor permissions'). It does not explicitly name alternatives or state when not to use the tool, though the scope and constraints make that largely inferable.

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 annotation, the description adds substantial behavioral context: it returns findings grouped by check, provides plain-language detail per item, only inspects configuration state, and requires instructor permissions. There is no contradiction with 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?

Three sentences with no filler: purpose and output are front-loaded, exclusions and prerequisites are grouped afterward. Each sentence contributes distinct 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 tool with two parameters and no output schema, the description covers the return shape (grouped findings with plain-language details), the optional checks behavior via the schema, the permission requirement, and the boundary versus alternative tools. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by explaining what the five check types correspond to in real configuration problems (e.g., missing due dates, unpublished items, gradebook weighting gaps), making the checks parameter more meaningful than the enum names 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 ('Run a factual course-readiness report') and enumerates the exact configuration problems it detects. It also differentiates itself from sibling tools by explicitly stating it does not inspect submissions or performance and names the alternatives, so an agent can tell it apart without opening the schema.

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

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

It states the tool's scope ('config-health report only') and gives concrete exclusion guidance: 'does not inspect student submissions or performance (see list_students_needing_attention / get_missing_submissions for those)'. It also adds the prerequisite that instructor permissions are required, giving clear when-to-use 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 declare destructiveHint=true and openWorldHint=true, so the scope for additional disclosure is limited. The description adds that the comment is added/appended, which is consistent with the annotation and confirms the write behavior, but it does not clarify subtle consequences: whether the comment appears to students, whether duplicate comments can accumulate, or whether edit/removal is possible. No contradiction with 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?

A single, well-constructed sentence with no wasted words; the action is front-loaded and mirrors the tool's name without reading as a tautology. Each word is doing something useful—excluding only the 'usage guidance'—but the sentence is so short that it leaves space for richer guidance.

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

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

Given the complexity of a write operation with no output schema and no example of a typical call, the description is adequate to know the rough invocation but incomplete on what a successful response looks like, whether an ID must point specifically to a student, and what authoritative failure modes exist. Its constraints, annotations, and schema coverage lower the burden substantially, leaving this at a minimum-viable completeness.

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 describes all four parameters, with 100% coverage, so the baseline is 3 even though the description itself adds no parameter detail. The description identifies the purpose (adding a text comment) but says nothing about the relationship among course_id, assignment_id, and user_id or validation rules beyond what the schema's own labels already imply.

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 names a specific verb ('Add'), a resource ('submission'), and the subject matter ('text comment'), making the action easy to distinguish from siblings like grade_submission or post_discussion_entry. However, it does not explicitly signal any sibling it is not, so an agent must infer that no other tool in the list handles this file.

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?

There is no guidance on when to use this tool versus alternatives such as grade_submission, list_submission_comments_needing_attention, post_discussion_entry, or send_conversation. A single sentence clarifying that comments are distinct from grades and discussion entries would have satisfied this dimension.

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 indicate destructiveHint: true, and the description aligns by noting creation action, though it doesn't detail irreversible effects or permission requirements. It clarifies that new_appointments define time slots and mentions the default draft behavior implicitly through the publish parameter. The description adds value by specifying the structure of new_appointments, which is not fully in the schema, but it doesn't disclose any potential side effects or prerequisites beyond what's in the schema.

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, and front-loads the core purpose and required attributes. It efficiently communicates the essential usage without redundant detail, earning a high score.

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

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

For an 11-parameter tool with no output schema, the description covers the essentials: required fields, the salient new_appointments format, and hints at the draft/publish behavior via the publish parameter. However, it doesn't mention return behavior or error cases, and doesn't detail all optional parameters, but given the schema's richness, it is reasonably complete for 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?

Schema description coverage is 100%, so parameters like context_codes and title are already well-documented. The description reinforces the required parameters and provides an example of context_code format ('course_123') and new_appointments structure, which adds a bit more clarity. However, it doesn't explain optional parameters like participant_type or max_appointments_per_participant beyond what the schema already states.

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 creates a new appointment group in Canvas Scheduler)Skip, with specific details about required parameters (context_code and title) and new_appointments as [start_at, end_at] pairs. It distinguishes from siblings like list_appointment_groups and update_appointment_group by focusing on creation, but doesn't explicitly name a sibling or contrast with other creation tools like create_calendar_event.

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 some usage context (e.g., provide at least one context_code and a title) but does not explicitly state when to use this tool versus alternatives like create_calendar_event or list_appointment_groups. It implies it's for setting up sign-up slots in Canvas Scheduler, but no direct comparison or exclusion of alternatives 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?

Annotations already declare openWorldHint and destructiveHint, but the description adds no side-effect context. It does not mention that creates may be irreversible, may become visible to students, or what happens on failure. No contradiction, but valuable context beyond the annotation is missing.

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 short sentence with zero wasted words; it is front-loaded and easy to parse. While it is minimal, there is no fluff or repetition, so it earns a high mark for conciseness.

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 with 7 parameters and no output schema, the description far too little. It provides no hint about return values, validation, side effects on students/enrollments, or how to verify the assignment. Both this and behavioral/usage gaps make it under-specified for an agent to reliably use.

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 structured schema already documents all parameters. The description text adds no extra meaning about nuances like how assignment_group_id or submission_types interact, so it default to the baseline 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?

States a specific verb (create) and resource (assignment) with a scope (course), which distinguishes it from update/delete/list tools. It does not explicitly name a sibling, but the resource name is precise enough that an agent can tell it apart from create_course or create_new_quiz.

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 on when to use this tool vs alternatives, when not to use it, orientation, or prerequisites (e.g., course must exist). An agent cannot decide between this and update_assignment/delete_assignment or between creating an assignment vs a new quiz based on the description.

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

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

Beyond the destructiveHint annotation, the description explains the behavior of omitted vs null date fields, the duplicate-override 422 failure mode, and the pseudonym-resolution prerequisite. This gives an agent actionable expectations about side effects without contradicting 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 carries essential constraint or behavior information, and the most important purpose is front-loaded. Despite being longer than a one-liner, it is dense and free of 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 mutating tool with no output schema, the description thoroughly covers parameters, preconditions, and errors. The only modest gap is that it does not state what a successful response returns, but an agent can still call 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?

Although schema coverage is 100%, the description adds the crucial cross-parameter invariants: exactly one selector must be provided, at least one date should be set, omitted fields remain unchanged while null removes them, and student_ids must be real Canvas user IDs. This is exactly the semantic glue the schema lacks.

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

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

States a specific verb and resource ('Create a due-date / availability override for a specific assignment') and immediately clarifies the three target modalities. The name and description are enough to distinguish it from sibling create/update tools such as create_assignment and set_student_assignment_dates.

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

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

Provides clear context and preconditions: exactly one target selector, at least one date field, ISO 8601 formatting, and a 422 pre-audit instruction via list_assignment_overrides. It does not explicitly map choice scenarios against a competing tool, but the workflow guidance is strong.

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 provides no behavioral details beyond the action itself. The annotation destructiveHint: true suggests the operation may have destructive side effects, but the description doesn't clarify what those are (e.g., overriding existing events, requiring specific permissions). It doesn't mention that it creates a permanent record or any side effects like notifications.

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, no fluff. It's appropriately concise for a simple create 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?

For a create operation, the description is minimal. It doesn't specify what the response will be (e.g., the created event object), which is important for the agent to process the result. Since there's no output schema, the description should at least mention the return type. It also doesn't mention any validation or error conditions.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema, such as explaining the relationship between start_at and end_at or the format of context_code. It doesn't compensate for any ambiguity in the schema.

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

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

The description states a clear verb ('Create') and resource ('new calendar event') and explicitly scopes to Canvas. It distinguishes from sibling tools like list_calendar_events and update_calendar_event by the verb 'create'. However, it doesn't specify whether this creates events in course, user, or group calendars, which could be ambiguous.

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 on when to use this vs alternatives. It doesn't mention that update_calendar_event exists for modifications or list_calendar_events for querying. No context on prerequisites like permissions or whether the context_code must exist.

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 asynchronous behavior: returns immediately with an export ID and initial workflow_state ('created'), and that the download link is time-limited. This adds meaningful context beyond the annotations. However, annotations include destructiveHint=true, and the description doesn't explicitly warn about resource consumption or cleanup, though it does note the async nature. No contradiction with 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 sentences, each earning its place: what it does, the async behavior, and the next step. Front-loaded with the core purpose, then critical behavioral detail, then routing guidance. No 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?

For a 2-parameter tool with full schema coverage and no output schema, the description covers the essential workflow: initiation, polling, and download link retrieval. It doesn't mention error cases or permission requirements, but the async flow and next-step routing are sufficient for an agent to call it correctly. The destructiveHint annotation is present but the description doesn't elaborate on what 'destructive' means here, which is a minor 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 coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the export_type enum values in plain language (common_cartridge for migration/backup, qti for assessments only, zip for Canvas-native files archive), which helps an agent choose correctly. This goes beyond the schema's terse 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 states a specific verb ('Start'), a resource ('Canvas course content export'), and the formats (Common Cartridge / QTI / zip). It clearly distinguishes this from related tools like get_content_export and list_content_exports by naming the asynchronous initiation role.

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 tells the agent to call get_content_export to poll progress and retrieve the download link, which is a clear when-to-use/next-step instruction. It also implies this tool is for starting exports, not checking them, which differentiates it from sibling tools.

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?

Usefully discloses the non-blocking behavior and immediate return of an ID and progress_url. With openWorldHint and destructiveHint annotations, the description does not add detail about what gets modified or overwritten in the destination course, whether rollback is possible, or what failure states look like. It still adds value over the annotations by explaining the asynchronous nature.

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

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

Two compact sentences carry the full purpose, the supported type list, and the polling advice. Information is front-loaded with no filler or redundant restatement of the schema.

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?

Coverage is solid for a 5-parameter, nested-object create tool with no output schema: it says what it returns and how to monitor completion. It does not describe the destructive side effects or exception/import issue conditions, but given the annotations and rich schema, it is mostly 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 already documents all five parameters. The description adds little new meaning about settings, selective_import, or date_shift_options, but it does clarify the return concept. 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?

States a specific action ('start a content migration'), lists all supported migration types, and frames the asynchronous result (migration ID and progress_url). This clearly separates it from the get/list migration tools and from content export 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?

Explains the async contract and directs follow-up polling to get_content_migration or progress_url, which is helpful usage context. It doesn't explicitly state when not to use it or mention non-migration alternatives, but the supported types plus async guidance are enough 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?

With annotations openWorldHint and destructiveHint already present, the description adds only the return value behavior. It doesn't elaborate on side effects of creating a course, permission requirements, or any additional consequences beyond the annotation already implying a write operation. No contradictions.

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 unnecessary details. The core purpose is front-loaded, and the return behavior is stated succinctly. No adverbial fluff or redundant phrases.

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 straightforward parameters, 100% schema coverage, and presence of annotations, the description is sufficient to allow an agent to call the tool. It correctly states a return value, which is the main non-schema behavior. The missing detail of destructive side effects is already captured 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 baseline is 3. The description itself does not explain any parameter beyond what the schema already provides; it only mentions the tool's purpose, not parameter meanings or interdependencies.

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 'Create a new course in a Canvas account' uses a specific verb and resource, clearly distinguishing it from update_course and other course-related tools. It also adds the return behavior ('Returns the created course object'), which reinforces the 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 for creating new courses but gives no explicit guidance on when to use it versus other course tools like update_course. It does provide context ('in a Canvas account') but no exclusions, prerequisites, or alternatives.

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

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

Annotations already declare destructiveHint=true, covering the write/mutation nature of the tool. The description adds no further behavioral disclosure such as permission requirements, side effects, or the silent announcement downgrade caveat, but it does not contradict the annotations. Since the annotations lower the burden, the description is adequate though not rich in behavioral 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?

A single front-loaded sentence with no filler; every word contributes to stating the action and scope. It is appropriately sized for a create operation, even though it could carry more contextual 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 tool with 8 parameters, no output schema, and subtle behavior such as the permission-dependent announcement downgrade, the one-sentence description is sparse. However, the input schema thoroughly documents all parameters, including the is_announcement caveat, and annotations cover the write side effect, so an agent consulting the full definition can call it correctly. The description alone would leave an agent unaware of the announcement dual-purpose.

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 eight parameters documented, including a useful behavioral note on is_announcement. The tool description itself adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Create'), resource ('discussion topic'), and scope ('in a course'). This clearly separates it from siblings like list_discussions, get_discussion, update_discussion, and delete_discussion. The modifier 'new' further signals it is not for editing existing discussions.

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 creating a new discussion topic, but it offers no explicit guidance on when to prefer this tool over alternatives such as update_discussion or post_discussion_entry, nor any prerequisites or exclusions. An agent must infer the selection criteria from the verb and resource alone.

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

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

Goes well beyond the annotations by disclosing that entries are sorted descending before sending, that the Canvas body key is grading_scheme_entry while the response uses grading_scheme, and that the response includes the id needed for activation. It also adds the admin requirement, which is not in the schema. The destructiveHint annotation is present but not contradicted by the description.

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 carries actionable information: definition, context selection, entry format, sorting, API key naming, and next-step activation. It is dense but not bloated, and the most critical usage guidance 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 an output schema is absent, the description compensates by telling the agent what will be returned and how to use it. All required parameters and their semantics are covered, along with the key behavioral quirks an agent needs to call 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining how the value field works as a lower-bound fraction, giving an explicit example, noting sorting behavior, and clarifying the mutual exclusivity of course_id and account_id in effect.

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

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

States a clear verb-resource pair: 'Create a new grading standard', and explains the concept as a letter-to-percentage scheme. It also differentiates itself from nearby siblings by noting that the returned id should be used with 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?

Provides explicit context: choose either course_id or account_id, with account requiring admin. It also tells the agent the follow-up use of the returned id with apply_grading_standard_to_course. It does not explicitly enumerate when not to use the tool, but the guidance is otherwise 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?

The annotations already carry openWorldHint=true and destructiveHint=true, so the safety profile is partially structured. However, the description adds nothing beyond the verb 'Create' — no mention of side effects on the course, duplicate-name behavior, publish-state implications, or whether the operation is reversible. For a mutating tool this gap is meaningful.

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

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

A single eight-word sentence, front-loaded with the action verb, with zero padding or redundancy. It earns its place and is easy to scan.

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

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

For a simple create operation with a 100%-documented schema and provided annotations, the description is minimally adequate for invoking with the two required parameters. However, there is no output schema, and the description never states that the created module (and its ID) is returned — an agent chaining to create_module_item would need that information to proceed.

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 five parameters (course_id, name, position, unlock_at, prerequisite_module_ids) are already documented. The description's 'in a course' adds only a trivial mapping to course_id, providing no real value beyond the schema, which matches the baseline 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 uses a specific verb ('Create') plus a concrete resource ('a new module') and scope ('in a course'), so an agent immediately understands the operation. It doesn't explicitly contrast with siblings like update_module or create_module_item, but the create+module language makes the purpose unmistakable.

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?

There is no when-to-use guidance, no exclusions, and no mention of prerequisites (e.g., the course must already exist). With siblings like update_module, create_module_item, and list_modules present, the description leaves it entirely to the agent to infer when this tool is the right choice.

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 merely states 'Add an item' without explaining behavioral nuances. It does not disclose that content_id is required for certain types (File, Page, Discussion, Assignment, Quiz) and that external_url is used for ExternalUrl/ExternalTool, nor any side effects or prerequisites. Given the destructiveHint=true annotation, the description adds little beyond what the annotation already signals, and it fails to elaborate on type-specific 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?

The description is a single, concise sentence that efficiently lists the eight allowed item types. It is front-loaded with the core action and avoids fluff, making it easy to parse. However, it is so terse that it omits important contextual details, so it is not a perfect 5.

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

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

Given the tool's complexity—7 parameters, 4 required, 8 types with conditional dependencies—the description is insufficient. It does not explain that content_id is required for most item types, that external_url is specific to ExternalUrl/ExternalTool, or that some types (SubHeader) need neither. It also omits any mention of prerequisites or return value. This leaves the agent guessing about the required combination of parameters for each type.

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%, meaning the input schema already documents all seven parameters with descriptions. The tool description adds no additional meaning about parameter relationships (e.g., that content_id is conditional on type or that external_url applies only to ExternalUrl/ExternalTool). Since the schema handles the heavy lifting, this is a baseline 3 with no extra value from the description.

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

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

The description clearly states the action ('Add an item') and the resource ('to a module'), and enumerates the supported item types (Assignment, Page, Quiz, etc.), making the tool's purpose obvious. It distinguishes from siblings like create_module (which creates the module itself) and create_assignment (which creates standalone content), but it does not explicitly contrast these alternatives, so it does not fully differentiate.

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 such as create_assignment, create_page, or create_module. It does not mention that this tool is for attaching content to a module rather than creating standalone items, nor does it suggest conditions like 'use this when you need to add an existing item to a module.' This leaves the agent to infer usage context from the name alone.

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

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

The annotations already signal a write operation via destructiveHint, and the description accurately describes a create action. It adds the LTI detail and the New vs. Classic quiz distinction, but does not elaborate on side effects, permissions, or draft/published behavior beyond the schema.

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, front-loaded sentences state the core operation and the key distinction from the alternative tool. There is no unnecessary detail or repetition of schema 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 create operation with 100% schema coverage and no output schema, the description provides the essential context: it creates a New Quiz, uses LTI, and tells the agent which sibling tool to use for Classic quizzes. It could add default behavior (e.g., draft vs. published), but the absence is not critical given the schema covers the published parameter.

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 parameters with descriptions, so the tool description does not need to restate them. However, the description also does not add any extra parameter-level guidance beyond what the schema 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 names a specific action ('Create'), a specific resource ('New Quiz'), and the target environment ('Canvas course'). It also distinguishes this from the Classic quiz tool, leaving no ambiguity about what this function 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 explicitly tells the agent to use create_quiz for Classic quizzes and identifies New Quizzes as the modern engine. This is clear alternative-selection guidance for an agent choosing between sibling tools.

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 potential side effects via destructiveHint and openWorldHint. The description adds valuable context beyond those flags by disclosing Canvas rate-limit behavior and instructing serial execution, which is not derivable from the schema or 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?

Four short sentences, each earning its place: the core action, supported types, rate-limit warning, and batching guidance. The most important scoping information is front-loaded and there is no 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?

The description is adequate for a create operation with a detailed input schema and explicit rate-limit handling. It omits return-value expectations, but no output schema exists and the core call contract is well covered by the schema and description combined.

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 80%, so the schema carries most parameter semantics. The description adds a helpful mapping of the 5 supported item types, but does not meaningfully elaborate on parameters like points_possible, course_id, or assignment_id beyond what the schema already documents.

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

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

The description states a specific action ('Create an item (question)'), the exact resource ('New Quiz (LTI)'), and enumerates the five supported item types. It clearly distinguishes this from sibling tools like create_new_quiz (quiz-level creation) and update_new_quiz_item (modification).

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 concrete operational guidance: call serially, avoid parallel calls, and chunk batches over 50 items with pauses due to Canvas rate limits. It does not explicitly mention alternatives like update/delete/list new_quiz_item, but the serialization and batching 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 annotations already provide openWorldHint=true and destructiveHint=true, signaling this tool may affect external state and requires caution. The description adds only that the page is 'new', implying creation rather than editing an existing page. It does not disclose behaviors like duplicate-title handling, authorization requirements, or whether publishing is affected. With annotations already carrying the main safety signals, the description adds some but limited behavioral 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 that says exactly what the tool does. There is no fluff or redundant wording, and every part of the 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?

Given the presence of a complete input schema, annotations, and an output schema, the description is mostly sufficient for correct tool selection and invocation. It might be slightly stronger with an explicit note about page uniqueness or permission requirements, but these are not necessary for the agent to fill required parameters and call 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?

The input schema covers all 5 parameters with descriptions, and schema description coverage is 100%, so the description does not need to compensate for missing docs. The description itself adds no parameter detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('create a new wiki page') and scopes it to a course, which clearly distinguishes it from siblings like list_pages, get_page, update_page, and delete_page. It is not a tautology because it adds the 'in a course' context and 'new' identifies creation rather than modification.

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 clear context: use this when you need to create a new wiki page in a course. It does not explicitly exclude alternatives or mention prerequisites, but the creation verb and 'new' imply the when-to-use condition. There are no misleading hints about when to choose this over a sibling.

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 indicate destructiveHint=true and openWorldHint=true, but the description adds no behavioral context beyond the simple assignment action. It does not disclose side effects, whether an existing peer review is replaced, or what happens on duplicate assignment—especially important given the destructive hint.

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 that is easy to parse and front-loads the core action. There is no redundant wording 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?

The tool is simple, has all four required parameters documented, and annotations provide some safety context. However, the description lacks any usage guidance or behavioral detail, leaving it as a minimum-viable definition rather than a fully helpful one.

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 provides 100% parameter coverage, describing each Canvas ID (user, course, assignment, submission). The description adds no additional semantic meaning beyond the schema, 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 ('Assign') with a clear resource ('a user to peer-review a submission'), and it is immediately distinguishable from sibling tools like delete_peer_review, list_peer_reviews, and get_submission_peer_reviews. It leaves no ambiguity about what action this tool performs.

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 states the action but gives no guidance on when to use this tool versus alternatives such as delete_peer_review or list_peer_reviews. There is no mention of prerequisites, constraints, or situations where this tool should be avoided.

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 non-obvious optional behavior of immediately linking to an assignment employment. However, given destructiveHint=true and openWorldHint=true, it does not clarify whether creation can overwrite existing rubrics, what side effects linking has, or what the response is. The annotations already cover some safety profile, and the description adds only modest behavioral detail.

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, no fluff, front-loaded with the core purpose and the optional behavior. Every word earns its place.

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

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

For a create operation with nested objects and 4 parameters, the description gives the essential flow. But the openWorldHint and destructiveHint suggest unknown or destructive behaviors that are not elaborated, and there is no output schema to describe the return value. 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?

Schema has 100% parameter documentation, so the description need not repeat field meanings. It does add the semantic link between the optional association object and assignment linking, but mostly relies on 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 clearly states the action ('create') and the object ('rubric in a course'), giving a specific verb-resource pairing. It does not explicitly distinguish from sibling read tools like list_rubrics or get_rubric, but the creating vs. reading distinction is obvious.

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?

Mentions the optional assignment association, which is useful contextual guidance about a key feature. However, it gives no indication of when to use this tool relative to other sibling tools, nor any prerequisites (e.g., course_id must exist) 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 declare destructiveHint=true, and the description complements this by revealing that deletion also cancels existing reservations and that cancel_reason triggers participant notifications. This adds meaningful behavioral detail beyond the annotation, without 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?

Two short sentences with no fluff. The primary action is front-loaded, and the optional parameter guidance is placed after the main statement. Every word earns its place.

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

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

For a simple delete tool with a clear destructive annotation and a 100% schema-documented required parameter, the description covers the key behavior and one optional usage detail. It does not mention the required appointment_group_id explicitly, but the schema covers it. No output schema exists, so no expectation to describe return values. Overall, it's sufficient.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds little beyond the schema: it mentions cancel_reason is used to notify participants, but the schema already says 'Message to include in cancellation notifications.' No additional syntax or meaning is provided, keeping this at the baseline.

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

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

The description states a specific verb ('Delete') and the resource ('appointment group'), and adds a concrete side effect ('cancel any existing reservations'). It clearly distinguishes this tool from its siblings (get, create, update, list) which do not delete.

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 like update_appointment_group. It only mentions the optional cancel_reason for notifications, but gives no guidance on when deletion is appropriate or when not to use it. The name implies deletion, but the absence of explicit usage context leaves some room for 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 declare destructiveHint=true, so the description's 'permanent' is consistent but adds little new information. It does not disclose potential cascading effects (e.g., on submissions/grades) or permission requirements, but given the annotation coverage, this is acceptable. 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?

Two short sentences with zero redundancy. The core action and key consequence (permanence) are front-loaded. Every word earns its place.

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

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

For a simple delete operation with two well-documented parameters, the description is sufficient. It covers the essential point of permanence. It could mention error conditions or side effects, but the annotations and schema already convey the destructive nature and required inputs.

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 describes both parameters (course_id and assignment_id) with clear definitions, achieving 100% coverage. The description adds no additional semantic value beyond what the schema already provides, so it meets the baseline.

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

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

The description clearly states the action (delete) and the resource (an assignment from a course). It is unambiguous and distinguishes itself from other delete tools like delete_new_quiz or delete_discussion by specifying the exact resource type.

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, no conditions, prerequisites, or exclusions. It simply states what it does, leaving the agent to infer usage from the name and 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 adds 'This action is permanent,' which goes beyond the destructiveHint annotation by informing the agent that the deletion is irreversible. It also clarifies the target as a discussion topic within a course. No contradiction with the annotations is present.

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 consists of two short sentences with no filler. The action is stated immediately, and the permanence warning is the only additional sentence, both earning their 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 two-parameter destructive operation, the description covers the target and permanence, and the schema fully documents the required IDs. It does not mention cascading deletion of replies or success/failure behavior, but those are not essential given the tool's simplicity and the annotations.

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

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

Schema description coverage is 100%, so the schema already documents the meaning of course_id and topic_id. The description adds no additional semantic detail for either parameter, so the baseline of 3 applies.

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

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

The description states a specific verb ('Delete'), a precise resource ('discussion topic'), and the scope ('from a course'). This clearly distinguishes it from discussion-related siblings like update_discussion/create_discussion and from other delete tools by naming the resource.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as update_discussion to close or archive a topic. It also states no exclusions or prerequisites, leaving the agent to infer usage context from the tool name.

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 conveys irreversibility beyond the destructiveHint annotation. It does not describe cascading effects or required permissions, but for a simple delete operation the added warning is meaningful.

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 the core action front-loaded. No filler or redundancy; the important permanence warning is included without bloat.

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-parameter destructive action, the description adequately equips an agent: it identifies the target, the required identifier, and the permanence of the action. It does not describe response behavior or side effects, but these are not critical for a basic 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 schema already documents 'file_id' with its type and meaning, and the description simply refers to 'a file by ID,' adding no deeper semantic detail. The schema carries the parameter documentation, so the description adds little beyond confirming the ID is used.

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 construction, 'Delete a file by ID,' which plainly states what the tool does. It is clearly distinguishable from sibling delete tools like delete_assignment or delete_discussion because it is specific to files.

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, such as update or list operations. While the intent is inferable, it does not state exclusions or conditions for use.

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. The description adds 'This action is permanent,' reinforcing destructive behavior, but offers no further context on side effects (e.g., cascading deletions, impact on grades). The LTI clarification and assignment_id hint are useful but not deep behavioral disclosure. No contradiction with annotations.

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

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

Two concise sentences with all key information front-loaded: action, resource, permanence, and identifier clarification. No redundant words or filler; every element 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 simple delete tool with two required parameters and annotations covering destructive/idempotent behavior, the description covers the essentials: what is deleted, permanence, and the critical identifier distinction. There is no output schema, so return-value documentation isn't needed. It lacks mention of downstream effects, but those are not required 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 coverage is 100% with both parameters described, so the baseline is 3. The description adds crucial meaning by clarifying that assignment_id (not quiz_id) is the correct identifier for this New Quiz deletion, which is not evident from the schema alone. This lifts the score to 4.

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 a New Quiz (LTI) from a Canvas course'), specifies the resource type (New Quiz), and differentiates it from siblings like delete_assignment and delete_new_quiz_item. It also explicitly notes the correct identifier (assignment_id not quiz_id), which distinguishes it from quiz-related 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 provides no explicit when-to-use guidance or comparison with alternatives. It only hints usage via the tool name and 'New Quiz (LTI)' context. The 'Use assignment_id (not quiz_id)' note is parameter selection guidance rather than usage direction, leaving an agent to infer when to choose this over delete_assignment or delete_new_quiz_item.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds 'This action is permanent,' which reinforces irreversibility beyond the annotation, and clarifies the LTI context. No contradiction with annotations. Given annotations, the description adds useful context without redundancy.

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, no filler. The action verb and resource are front-loaded, and the permanence warning is a single extra phrase. Every word earns its place.

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

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

For a simple delete operation with three well-documented parameters and annotations covering destructive behavior, the description is complete. It doesn't describe the return value, but for a delete that typically returns a success indicator, this is not a critical gap. The description is sufficient for an agent to call 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 description coverage is 100%: every parameter (item_id, course_id, assignment_id) has a clear description in the schema. The tool description adds no additional parameter semantics beyond what the schema already 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 states a specific verb (Delete) and a specific resource (an item/question from a New Quiz LTI). It clearly distinguishes from the sibling tool delete_new_quiz, which deletes the entire quiz, and from create/update/get/list_new_quiz_item tools. The 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 description gives clear context: it is for deleting a single item from a New Quiz, and it explicitly notes the LTI variant. It does not mention exclusions or name alternatives, but the tool name and description make the appropriate use case obvious. A slightly higher score would require explicit 'when-not' guidance, but the clarity is sufficient.

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 annotation destructiveHint=true already flags the destructive nature; the description adds a valuable 'permanent' warning that goes beyond the hint. No further behavioral claims are made, but for a simple delete action this is sufficient.

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 redundant wording. The action is stated firsthola and the irreversible consequence is highlighted immediately.

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 only two documented parameters in the schema)Skip the context is sufficient. The permanent consequence is stated)Skip and the annotations cover safety profile. It does not discuss prerequisites or edge cases, but none are essential for 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 documents both required parameters with 100% coverage. The description adds no parameter-level information, so the schema is the primary source; this is an acceptable baseline.

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

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

States a specific verb ('Delete'), a precise object ('wiki page'), and the containment scope ('from a course'). This clearly distinguishes it from deletion tools for other resource types.

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 you need to delete a wiki page. However, it offers no explicit guidance on alternatives, prerequisites, or situations where this tool should not be used.

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 indicate destructiveHint=true, and the description adds the important clarification that the action is permanent. This goes beyond the structured annotation by telling the agent the operation is irreversible.

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 filler. It front-loads the action and then adds the key permanence warning, earning every word.

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, the description covers the core action and permanence, and the schema documents all parameters. It lacks only minor context such as what happens after removal, but this is not critical given the annotations and simple scope.

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 four parameters individually described in the input schema. The tool description adds no parameter-specific meaning, so it does not exceed the baseline for fully documented schemas.

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 a clear resource ('a peer review assignment from a submission'), making the action unambiguous. It is immediately distinguishable from sibling tools like create_peer_review and list_peer_reviews.

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 use case is implied by the action statement, but there is no explicit guidance about when to use this tool vs alternatives such as create_peer_review or delete_assignment. The description does not mention 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?

Goes beyond the readOnlyHint annotation by disclosing response format differences (text vs. base64 binary) and a 10 MB size refusal. No contradiction with 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 concise, front-loaded sentences with no filler. Each sentence adds a distinct useful fact: core action, output encoding, and a hard size limit.

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-only tool with two parameters and no output schema, the description adequately covers encoding and size constraints. It omits minor operational details like error behavior, but nothing critical for basic invocation is missing.

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

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

Schema has 100% description coverage for both file_id and course_id. The description mainly restates the schema's meaning and adds no deep semantic detail, so it neither fails nor substantially enhances the structured definitions.

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

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

States a specific verb and resource: 'Download the content of a Canvas file by ID.' It clearly indicates this tool retrieves file content, though it does not explicitly distinguish itself from the sibling get_file, so it misses the differentiation that would earn a 5.

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

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

Provides no guidance on when to use this tool versus alternatives such as get_file or list_files. The description explains what the tool does but gives no conditions, exclusions, or comparison to siblings.

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 mutation, but the description does not disclose behavioral traits beyond that. It doesn't mention that enrollment may send invitations, that changing enrollment_state affects user access, that re-enrolling an existing user may update their enrollment, or that this operation may be irreversible. With destructiveHint=true, the description carries a burden to explain consequences, and it fails to do so.

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 that front-loads the core action and key parameter. It earns its place with no filler, though it could add a brief note about enrollment_state behavior 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?

For a mutation tool with destructiveHint=true and no output schema, the description is thin. It doesn't explain what happens after enrollment (e.g., invitation workflow, default state), what the response contains, or any side effects. An agent would need to infer too much about the operation's consequences.

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 four parameters. The description adds the phrase 'with a specified role', which maps to the 'type' parameter, but it doesn't add meaning beyond the schema's own descriptions. Baseline 3 is appropriate because the schema does the heavy lifting.

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 ('Enroll'), a resource ('a user in a course'), and a key parameter ('with a specified role'). It clearly distinguishes the tool from siblings like list_enrollments and remove_enrollment, 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 the primary use case: adding a user to a course with a role. It doesn't explicitly state when to use this tool versus alternatives like list_course_enrollments or remove_enrollment, nor does it mention prerequisites (e.g., the user must exist, the course must be active). The context is clear but exclusions and alternatives are not 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?

Even with readOnlyHint=true, the description adds substantial behavioral context: one student per call, curves/fudge points not reflected, discrepancy caveat threshold, grading-period reconciliation behavior, and pseudonym resolution requirements. This goes well beyond what the 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 front-loaded with the core purpose, followed by a clear use-case sentence and a tight bulleted limitations section. Every sentence contributes meaningful information, and the structure makes it easy for an agent to scan.

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

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

There is no output schema, but the description enumerates what the tool returns: group weights, drop rules, per-group breakdowns, letter grade, and reconciliation check. Combined with the limitations, this is complete enough for an agent to call the tool correctly and interpret its result.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description repeats some parameter facts (e.g., omitting student_id) but adds no new parameter-level semantics beyond what the schema states.

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-resource pair: 'Recomputes and explains the weighted course grade for a student,' then enumerates the exact components of the computation. This detail distinguishes it from siblings like project_grade or explain_grading_policy even without naming 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?

It gives an explicit trigger: '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 lists important limitations, but it does not name alternatives or say when not to use this tool versus a sibling.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false Tal. The description adds valuable behavioral detail: the exact policy sections returned, the permission-dependent output differences, and the plain-language summary format. Notably, it also reveals that parts of the policy may be hidden for students, which is important 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?

Information is front-loaded with the core purpose in the first sentence, followed by well-organized bullet points covering each policy area, and a clear permission-related caveat at the end. 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?

Given there is no output schema, the description does a good job of specifying what the returned explanation covers (four policy areas plus a plain-language summary) and the permission-dependent content. It stops short of describing the exact output shape, but for this kind of explanatory read-only tool, the context is largely sufficient.

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 single course_id parameter; the schema fully documents it as a Canvas course ID. The description adds no parameter-level semantics beyond what is already in the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('explains') and names exactly what the tool covers: missing-submission policy, late-submission policy, assignment-group weighting, and grading scheme. This is clearly distinguishable from sibling tools like get_course or list_assignment_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?

Provides clear context on when the tool is appropriate and includes a permission caveat (students vs. instructors/admins receive different sections). It does not explicitly name an alternative tool, but the usage scenario is clear enough without one.

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 alerting agents this is a safe read. The description adds meaningful behavior beyond the schema: it groups by display name + size, explicitly states file listings carry no hash, and clarifies same-name different-size files are excluded. That's real algorithmic disclosure. Would be a 5 if the return shape were described, but it is not.

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 compact, informative, and front-loads the core purpose in the first sentence. Each clause earns its place – the cleanup use case, the lack of content hash, and the same-name-different-size exclusion are all decision-relevant.

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 fully explains the algorithm, the reasoning, and how results relate to an action (delete_file). It does not specify the output shape, but with no output schema and a read-only tool that returns duplicate listings, the behavior is sufficiently clear for an agent to invoke it. Minor gap: it doesn't state limits on how many duplicates or performance caveats, but these are not critical.

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 explains both parameters. The description adds context for why folder_id matters (scoping to subfolders) and clarifies the grouping criteria, but doesn't go far beyond schema semantics. Baseline 3 for full schema coverage 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 ('find') and resource ('duplicate files in a course Files area'), with a precise working definition ('same name and size'). It also gives the rationale (flags by accessibility checkers) and names the complementary cleanup tool, which clearly distinguishes it from file-listing siblings like list_files and get_file.

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 the tool (when accessibility checkers flag duplicates from course copies) and what to do with results (clean up with delete_file). It doesn't explicitly say when NOT to use it, but it does note the grouping limitation, which implies when it's insufficient. No alternative tool is directly contrasted, but the context 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?

The annotations already mark this as read-only, but the description adds valuable behavioral detail beyond that: truncation behavior with `truncated: true`, course-scan ordering by most recent term, and per-course error handling via `courses_failed`. This is strong transparency, especially given the partial-failure semantics.

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 sentences, with the core purpose front-loaded and every sentence contributing operational details. There is no filler, repetition of the name, or redundant restatement of the schema.

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 having no output schema, the description explains what the caller can expect: matching courses, enrollment state, last activity, `truncated`, and `courses_failed`. Combined with the parameters and annotations, an agent has everything needed to invoke and interpret 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?

The input schema already covers all three parameters, so the baseline is 3. The description adds meaning beyond the schema by explaining defaults (`include_concluded` defaults to true), the effect of `max_courses`, and how `truncated` is set when the cap is exceeded. This enriches 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 states a specific verb ('Search'), a specific resource ('the caller's teaching courses'), and a clear object ('a student by name, login, or email'). It also specifies what is reported, which distinguishes it from nearby search/list tools like search_users or list_course_users.

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 clear context for when this tool is appropriate: searching across the caller's own teaching courses, including concluded ones by default. It does not explicitly name alternatives or exclusions, but the scope and behavior are precise enough for an agent to select it correctly.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate that this is a safe read. However, the description adds no behavioral context beyond the annotations—it does not mention error behavior, what 'details' are included, or any limitations. With annotation coverage in place, the description contributes little additional transparency.

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 short, front-loaded sentence with no filler. Every word earns its place, and the key information—verb, resource, and parameter—is immediately visible.

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

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

For a single-parameter, read-only lookup with full schema coverage and safety annotations, the description is nearly complete. It explains what the tool does and what input it needs. A minor gap is that it does not hint at what 'details' are returned, but for this simple tool that is not a significant omission.

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 documents account_id as 'The Canvas account ID' with 100% coverage, so the baseline applies. The description's 'by ID' mirrors the schema without adding new semantic detail such as format, range, or where to find valid IDs.

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

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

The description states a specific verb ('Get'), a specific resource ('Canvas account'), and the lookup key ('by ID'). It clearly distinguishes this from sibling tools like list_accounts or list_sub_accounts, which are list operations, while this is a single-account fetch.

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 the tool is used when you have an account ID and need its details, but it does not explicitly state when to prefer this over alternatives such as list_accounts or list_sub_accounts. There is no exclusion or alternative guidance, so the usage context is clear but not fully elaborated.

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 the notion that it lists metadata (report types) rather than report content. However, it discloses no additional behavioral traits such as pagination, output format, or relationship to report generation.

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 concise sentence with no filler, front-loading the verb and resource. It earns its place without 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?

For a simple read-only listing tool with one parameter, the description and schema together are nearly complete. It could mention what the returned report types look like (e.g., IDs and names) since there is no output schema, but this is a minor 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%, so the single parameter account_id is already fully documented. The description adds no extra meaning about the parameter's role or constraints beyond what the schema provides, so the baseline 3 applies.

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

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

The description uses a specific verb 'List' and a clear resource 'available report types' scoped to a Canvas account. This distinguishes it from sibling tools, none of which focus on listing report types.

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 or any exclusions. The purpose statement implies usage, but there's no explicit context like 'use this before generating a report' or indication of what the result is for.

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 cover safety. It adds that the response includes time slots and participant counts, which is useful, but it is ambiguous whether these are included by default or only via the include parameter.

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

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

A single sentence that front-loads the operation and resource, then adds the key response attributes. There is no filler or repetition of schema details, making it maximally 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?

For a read-only single-getter with two parameters and complete schema documentation, the description is sufficient. Minor gaps remain: it does not mention the 'child_events' include option nor provide explicit sibling distinctions, but these are not critical for a correct call.

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 only a loose mapping of 'time slots' and 'participant counts' to the include enum values, but no additional parameter meaning 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?

States a specific verb ('Get'), resource ('appointment group'), and scope ('single...by ID'). This clearly distinguishes it from list_appointment_groups and the mutating siblings, and mentions the included data (time slots, participant counts), leaving no doubt 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 singular 'by ID' implies this is the tool to use when an appointment group ID is already known, but the description never explicitly contrasts it with list_appointment_groups or update_appointment_group. No exclusions or alternative routing are provided, so usage context 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds minimal behavioral context beyond listing include options, but does not explain return shape, edge cases, or permission requirements. No contradiction with annotations.

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

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

Two concise sentences with no filler. The primary purpose is front-loaded, and the include guidance is packed into a short second sentence that 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?

The definition is adequate for a simple get tool, but it leaves ambiguity around the duplicate `all_dates` boolean vs the `include` enum value 'all_dates', and does not describe return values or error behavior despite there being no output schema. For a tool with 6 parameters and no output schema, this is a clear 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%, so the schema already documents all parameters. The description's mention of `include` and its values adds little beyond the schema's own enum and descriptions; it only lightly reinforces that these fields are optional.

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 ('Get'), a resource ('assignment'), and an identifier ('by ID'), and clarifies it operates on a single assignment, distinguishing it from list_assignments and mutating assignment tools. It also hints at optional fields available via the include parameter.

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 usage context is implied: use this for a single assignment by ID, and use `include` to request optional fields. However, it does not explicitly mention alternatives like list_assignments or state when not to use this tool, leaving routing 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 declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate read-only safety. It adds valuable behavioral detail: the specific analytics returned (min, max, median, quartiles, submission count, tardiness breakdown) and the scoping behavior of assignment_id. This goes beyond the annotations, though it doesn't mention edge cases like empty results or performance implications, which is acceptable given the read-only 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 exactly two sentences, with the core purpose stated first and the scoping option second. Every word earns its place; there is no fluff or repetition. Front-loading the primary action and then clarifying the optional parameter is an efficient and clear structure.

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 tool with only two parameters and no output schema, the description is complete. It specifies what analytics are returned (statistical summary, submission count, tardiness breakdown), the scoping logic, and the required course_id implicit in the schema. The agent has all the information needed to correctly invoke the tool and interpret the result without an output schema.

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

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

Schema description coverage is 100%, and the schema already documents both parameters with clear descriptions, including the scoping behavior of assignment_id ('Scope the result to a single assignment ID. Omit to return analytics for all assignments.'). The description essentially restates this same information, adding no new parameter semantics beyond what the schema provides. Thus the baseline score 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 states a specific verb ('Get'), a clear resource ('score distribution analytics for assignments'), and the exact scope (a course, optionally a single assignment). It distinguishes from sibling analytics tools like get_course_analytics and get_student_analytics by focusing on assignment-level statistics, making intent 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?

It clearly explains how to scope to one assignment or all assignments, giving explicit usage context. However, it does not directly mention when to prefer this over alternative analytics tools (e.g., get_course_analytics), nor does it offer exclusions. The 'omit to return all' guidance is strong, but it lacks an explicit comparison to siblings, so a 4 rather than 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 already declare readOnlyHint=true and openWorldHint=true. The description adds meaningful state behavior: attachment is null until 'exported', the download link is time-limited, and re-fetching is needed. This goes beyond the annotations without contradicting 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?

Two sentences, front-loaded with the core purpose, followed by the most important state/expiry behavior. No filler or repeated schema 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 description covers the main use case (polling for export status), the meaningful states (created/exporting/exported/failed), the attachment null behavior, and the time-limited URL with a re-fetch remediation. This is sufficient for an agent to invoke and interpret the result without an output schema.

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

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

Schema coverage is 100% (course_id and content_export_id have descriptions), so the description is not required to repeat parameter docs. It does not add extra semantics about the parameters, so a 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?

Begins with a specific verb+object construction: 'Get the status of a content export.' This clearly identifies both the action and the resource, and the detail about workflow_state and attachment distinguishes it from other get_* 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?

Clear context is provided: this is the status-checking tool for content exports, and the description implies a polling use case. However, it never explicitly names sibling tools like create_content_export or list_content_exports, so it leaves the when-to-use vs alternatives distinction 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?

Annotations already establish read-only and open-world behavior, so the description adds value by explaining the polling behavior tied to workflow_state. It discloses that progress_url should be polled for live updates and defines what 'completed' means, which is useful 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?

Two sentences with no filler. The core purpose is front-loaded, and the conditional polling instruction is concise and directly actionable.

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

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

For a simple status-retrieval tool with readOnlyHint and openWorldHint annotations, the description covers the essential behavior and return-state handling. It does not describe all possible workflow_state values, but it covers the ones needed for correct operation, so it is nearly 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?

The input schema already provides 100% coverage for both course_id and migration_id with clear descriptions. The tool description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description starts with 'Get the status of a single content migration,' naming a specific verb, resource, and granularity. The word 'single' clearly distinguishes this from list_content_migrations or list_content_exports, so an agent can select the right tool without opening schemas.

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

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

It gives actionable context: when workflow_state is 'running', poll progress_url, and when 'completed', the migration is done. It does not explicitly contrast with sibling alternatives, but the context is clear enough for the primary usage pattern.

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 convey readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by specifying that the full message thread is returned, which goes 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?

A single, focused sentence that front-loads the action and scope. There is no filler, repetition, 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 read-only getter with one parameter, the description plus annotations cover the essential call requirements. It could be slightly more explicit about response contents or behavior for invalid IDs, but nothing critical is missing.

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

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

The schema description covers 100% of parameters, with 'conversation_id' described as 'The conversation ID.' The tool description does not need to add more, so the baseline score 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 identifies the specific verb ('get') and resource ('a single conversation') and adds the distinguishing detail 'with its full message thread.' This separates it from sibling tools like list_conversations and get_conversation_unread_count without ambiguity.

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

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

The description implies this tool is for retrieving one conversation rather than a list or a count, but it does not explicitly name alternatives or state when not to use it. The usage context is clear enough to infer, but not directly stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and volatility. The description adds no new behavioral context beyond the read-only count scope; it does not explain response shape, auth-specific edge cases, or what 'unread' means, but it also does not contradict 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?

A single sentence with no redundant wording. The action and target are front-loaded, making it immediately scannable.

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 count operation, the description is sufficiently complete: it states what is returned (a count), for whom, and of what resource. No output schema exists, but 'the number of unread conversations' makes the return intent clear enough.

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?

There are zero parameters, so the schema has nothing to document and the baseline for this dimension is 4. The phrase 'for the authenticated user' communicates the implicit auth context relevant to the tool's operation, but no parameter meaning 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 uses a specific verb ('Get') and a precise resource ('the number of unread conversations'), and scopes it to the authenticated user. It is clearly distinguishable from siblings like list_conversations or get_conversation by its aggregate-count intent, though it does not explicitly name those alternatives.

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 use case is implied: call this when you need the unread-conversation count for the current user. However, there is no explicit when-to-use/when-not-to-use guidance or any mention of alternatives such as list_conversations, so an agent must infer the decision on its own.

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 reveals a crucial behavioral detail: the endpoint defaults to requesting only term and total_students, and passing include replaces the entire default set. This is key for an agent to understand what it will get and why certain fields may be absent. It also suggests typical include values, which is further context not present in 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 front-loaded and brief, opening with the purpose statement followed by default behavior and a directive on include. The third sentence lists examples (teachers, permissions, syllabus_body, sections) that overlap with the exhaustive enum in the schema, but it still surfaces the most relevant ones, so it's slightly redundant but not wordy.

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 three parameters and no output schema, the description covers the necessary behavior: the default fields, the mechanism for customizing fields, and the example includes. It does not spell out the exact response shape, but it gives enough context that an agent can anticipate the response, given the get-course semantics and the readOnly annotation.

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 describes each parameter, but the description adds essential semantics not trapped in the schema: that term and total_students are the defaults, and that include replaces rather than extends them. This is precisely the kind of 'replacement vs additive' nuance an agent cannot infer from the schema alone. teacher_limit's relationship to include=teachers is already in the schema, so schema coverage is high; the description adds meaning to include beyond that.

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

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

The description clearly opens with 'Get details for a single course,' which names the action and resource, and the phrase 'single course' distinguishes it from sibling list tools like list_courses and get_my_courses. It also flags the default field set, reinforcing that this is the detail-retrieval tool, not an activity stream or syllabus-only endpoint.

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 context for when to use this tool: when you need a single course's details. Though it does not explicitly name alternative tools or provide when-not-to-use / exclusion rules, the scope 'single course' is a clear enough pointer and the include/parameter guidance further conditions its use.

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