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

With no annotations, the description carries the full burden, and it does well: it asserts 'read-only by construction — it cannot issue a write even if asked to' and explains that max_chars bounds the payload. It stops short of covering auth requirements, rate limits, or error/status behavior, so it isn't fully complete.

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

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

Front-loaded with the key framing ('escape hatch') followed by clean per-argument docs. The rationale sentence about a thousand operations is slightly verbose but earns its place by justifying the tool's existence.

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

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

An output schema exists so return values need no explanation, and the description covers scope, safety, and all three parameters with examples. Only error handling and auth expectations are unaddressed, which is a minor gap for a generic GET passthrough.

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 0%, so the description must compensate and does: it explains the path format (under /api/v1, with a concrete example and full-URL fallback), params_json as a JSON object with a sample including per_page and include[] syntax, and max_chars with the 0=server-default convention.

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 ('GET any Canvas REST endpoint') and frames itself explicitly as an escape hatch for operations not covered by dedicated tools. An agent can immediately distinguish this from the many resource-specific siblings.

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

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

Gives explicit when-to-use: the dedicated tools cover common teaching operations, 'use this for the rest.' The condition selecting this tool over its ~40 siblings is stated directly rather than left to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses that no token material is revealed (a security/privacy guarantee an agent could not infer) and explains that the 'tools' section reports what the server published versus what a safety flag withheld. It stops short of stating auth requirements or error behavior, but the disclosure of non-sensitive output and the withheld-tools semantics is substantive.

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

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

Three tight sentences with the core purpose front-loaded, followed by the safety guarantee, then the trigger conditions. No filler and nothing repeated from structured fields.

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

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

An output schema exists, so return values need not be enumerated, yet the description still usefully characterises the 'tools' section of the response. For a zero-parameter, no-annotation diagnostic tool, this covers everything an agent needs to decide to call it and interpret the result.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter surface for the description to clarify. The description adds nothing about parameters because nothing exists to add.

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 (Check) and resource (Canvas connectivity, identity, enabled tool tiers), which no sibling tool covers — every sibling is a content operation. An agent can immediately tell this is the server's diagnostic/probe tool rather than a Canvas data operation.

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

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

Gives two explicit, actionable triggers: 'Call this first whenever another Canvas tool fails' and 'when a tool you expected is missing.' These are unambiguous when-to-use conditions that no other tool's description would need to state.

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 no annotations, the description carries the full burden and does so well: it discloses the mutation ('MUTATES STUDENT RECORDS'), the asynchronous processing model, that it returns a Progress object with delayed visibility, and the absence of a partial-failure report. These are exactly the traits an agent cannot infer from 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?

Front-loaded with purpose, mutation warning, and async caveat before the args list. The consequence of the write is stated twice (the all-caps line and the 'highest-consequence call' paragraph), which is mild redundancy, but every section still carries 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?

Covers purpose, side effects, async timing, verification path, and all parameter formats for a 3-param bulk mutation. The output schema exists, and the description still usefully summarizes the Progress return, so nothing an agent needs is missing.

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

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

Schema description coverage is 0%, so the description must compensate and it does: it documents all three parameters, gives concrete grades_json examples including both the object and bare-string shorthand forms, and states the course_id default behavior.

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 with an explicit scope qualifier ('Post many grades to one assignment at once'), which immediately separates it from the single-grade sibling canvas_grade_submission. An agent can identify the tool without opening the schema.

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

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

Gives a clear operational precondition ('show the instructor the complete table ... and get an explicit go-ahead; never assemble one from inference') and names the verification follow-up (canvas_list_submissions). It never states the when-NOT condition, e.g. that single grades should go through canvas_grade_submission, so it falls short of full alternative routing.

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 no annotations, the description carries the full burden and does: it declares the write/mutation, the default-unpublished visibility state, the UTC storage caveat that makes naive local deadlines wrong, and the default values for grading_type, submission_types and course_id. That is exactly the behavioral context an agent needs before calling.

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

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

Front-loads purpose and the mutation/visibility warning before the Args block, then keeps one tight line per parameter. The timezone note is long but earns its place by preventing a concrete, common error.

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?

A 12-parameter mutation tool with an output schema present, so return values need not be explained. Everything else an agent needs — mutation semantics, visibility default, date format, enum values, course scoping — is covered.

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

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

Schema description coverage is 0%, so the description must compensate and it does, documenting all 12 parameters including the enumerated values for submission_types and grading_type, the ISO 8601 UTC format with a worked example, and the semantics of omit_from_final_grade and points_possible (omit for ungraded).

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

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

Opens with a specific verb+resource ("Create an assignment") and immediately flags the mutation ("MUTATES the course"), which cleanly separates it from canvas_update_assignment and the read-only siblings. An agent can pick this tool without opening the schema.

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

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

Gives a clear conditional rule for the risky flag: default unpublished, pass published=True only when the instructor confirms readiness. It also routes the agent to canvas_list_assignment_groups for the group id. It stops short of naming when to prefer canvas_update_assignment or listing prerequisites, so it is strong but not exhaustive.

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 no annotations, the description carries the full behavioral burden. It correctly and prominently flags 'MUTATES the course', which is valuable, but does not disclose required permissions, whether duplicate groups are allowed, error behavior, or side effects beyond creation. The mutation flag is useful but incomplete.

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 purpose is front-loaded in the first sentence and the mutation warning is immediate. The Args block is structured and necessary given the schema's lack of descriptions, though slightly list-like rather than fully integrated. No sentences are wasted.

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

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

For a 4-parameter mutation tool with no annotations and an output schema, the description covers parameter semantics and mutation status well, and the output schema handles return values. However, it omits usage context relative to siblings and behavioral details like permissions, leaving some gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It explains all four parameters: name with an example, group_weight as a percentage for weighted courses, position as a 1-based slot, and course_id as a numeric ID defaulting to CANVAS_DEFAULT_COURSE_ID. This fully covers the semantic gap in the schema.

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

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

States a specific verb and resource ('Create an assignment group') and clarifies the domain with '(a gradebook category)'. This is clear and distinct from sibling tools like canvas_create_assignment, though it does not explicitly name or differentiate itself from 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 description gives parameter-level usage ('Omit for unweighted', 'omit to append') but provides no guidance on when to choose this tool over alternatives such as canvas_list_assignment_groups or canvas_create_assignment. No prerequisites or exclusions are mentioned.

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

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

With no annotations, the description carries the full burden and does well: it flags 'MUTATES the course' and discloses the important side effect that the event appears on every enrolled student's calendar. It does not cover permission/auth requirements or what happens if a course_id is invalid, so it is strong but not exhaustive.

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

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

Front-loads the action and the mutation warning, then usage guidance, then a compact Args block. Every sentence earns its place, and the arg annotations are necessary given 0% schema coverage rather than redundant.

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

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

An output schema exists so return values need not be explained, and the description still covers the mutation side effect, student-wide visibility, usage boundaries, and all parameter semantics. For a 6-param mutation tool with no annotations, nothing essential is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents all six parameters: ISO 8601 UTC format with a concrete example for start_at, omitting end_at for a point-in-time event, HTML allowed in description, location meaning, and the CANVAS_DEFAULT_COURSE_ID default for course_id. This adds substantial meaning beyond the bare schema titles.

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 calendar event on the course calendar') and immediately scopes it ('MUTATES the course'). It also carves out a boundary against a sibling concept by ruling out assignment due dates, letting an agent distinguish this from canvas_create_assignment without opening either schema.

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

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

Gives explicit when-to-use examples (class meetings, office hours, guest lectures) and an explicit when-not-to-use case pointing to the right alternative (assignment due dates belong on the assignment so the gradebook sees them). Both the positive and negative routing conditions are 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?

With no annotations, the description carries the full behavioral burden and does well: it declares the write/mutation nature, the unpublished default, the notification side effect of publishing, and defaults for threaded/pinned. It omits permission requirements and whether an existing topic can be overwritten, so it is strong but not exhaustive.

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 purpose and the mutation warning are front-loaded in the first two lines, and the args list is compact with no filler sentences. The bulleted arg block is a little listy, but every entry adds meaning rather than repeating the schema titles.

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 7-parameter mutating tool with an output schema already covering returns, the description supplies the missing pieces an agent needs: default publish state, notification side effect, and per-parameter semantics. Only auth/permission expectations and failure behavior are absent, which is a minor gap given the output schema exists.

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 0%, so the description must compensate, and it does: all seven parameters are explained with semantics beyond the schema, including 'message: prompt body (HTML allowed)', the default-off published flag, and 'course_id: numeric course id; defaults to CANVAS_DEFAULT_COURSE_ID'. Defaults and behavioral effects of each toggle (require_initial_post, threaded, pinned) are clarified.

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 discussion topic') and immediately flags the mutation with 'MUTATES the course', which is more than a restatement of the name. It does not explicitly contrast itself with neighbors like canvas_create_page or canvas_post_announcement, so sibling differentiation is only implied by the resource noun.

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 the intended workflow context clearly: 'Defaults to UNPUBLISHED so you can review it before students see it' tells the agent this is the draft-then-publish path, and it warns that publishing notifies students. It gives no explicit when-not or named alternative tool, so it lands at clear-context without exclusions.

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 no annotations, the description carries the full burden and does well: it flags that the call MUTATES the course and discloses the important default that the module is UNPUBLISHED (invisible to students). It omits permission/auth requirements and idempotency, keeping it below a 5.

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

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

Front-loaded with the action and the MUTATES warning, followed by a container-vs-items clarification, then a compact per-argument list. Every line adds information with no filler.

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

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

An output schema exists, so return values need no explanation, and the description covers the mutation semantics and the non-obvious unpublished default that annotations (absent) would otherwise have to carry. Nothing essential to a correct invocation is missing.

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

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

Schema description coverage is 0%, yet the description documents all four parameters with meaning beyond the schema: position is a 1-based slot with omit-to-append semantics, published controls immediate student visibility, and course_id falls back to CANVAS_DEFAULT_COURSE_ID. This fully compensates for the empty schema descriptions.

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

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

States a specific verb (Create) and resource (course module), and explicitly distinguishes the module container from its contents by naming canvas_create_module_item. An agent can separate this from canvas_update_module and canvas_create_module_item without opening any schema.

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

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

Clearly implies the workflow context by stating a module is an empty container until items are added via canvas_create_module_item, which routes the agent to the follow-up tool. It stops short of explicit when-not guidance or naming canvas_update_module as the alternative for existing modules.

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 no annotations provided, the description carries the full behavioral burden. It discloses the critical trait that this MUTATES the course, which is genuinely useful, but says nothing about required permissions/role, reversibility, or whether duplicate items are allowed. Adequate but with clear gaps for a write operation.

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

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

Front-loaded with the action and the mutation warning, then organized into a conditional table plus a clean Args block. The Args section is verbose, but it is not redundant with the schema (0% coverage), so it earns its space; only the repetition of "for item_type=X" phrasing is mildly wasteful.

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

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

An output schema exists, so return values need not be explained. For a 9-param mutation tool with no annotations, the description covers the params and the mutation risk well; the remaining gap is the absence of permission/auth prerequisites that an agent would want before attempting the write.

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 0%, so the description must compensate entirely, and it does: every one of the 9 params is explained, including defaults (course_id, position append behavior, indent top level) and the conditional dependency between item_type and which id field to supply. This is meaning that exists nowhere else in the structured data.

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 ("Add an item to a module") and immediately flags the mutation, which is exactly what an agent needs to distinguish this from canvas_create_module or canvas_update_module. The one-line summary is unambiguous about scope.

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 the strongest form of conditional guidance: a lookup table mapping each item_type to the id field it requires (content_id, page_url, external_url, or neither). It does not, however, say when to prefer this tool over creating the underlying object first (e.g. canvas_create_assignment), so it clears the bar for context without covering exclusions.

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 no annotations, the description carries the full burden and does well: it discloses the mutation, the UNPUBLISHED default, and the non-obvious slug/url behavior (returned url vs numeric page_id). It omits permission/auth requirements and any duplicate-title or error behavior, keeping it short of a 5.

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

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

Front-loaded with purpose and the critical mutation/default caveats before the Args block, and the url-slug note is placed where it matters. Slightly verbose but every line carries 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 5-param mutation tool with no annotations and an output schema present, the description covers the essentials: what it mutates, default state, and the meaning of the returned url (which the output schema alone would not convey). Missing only permission/precondition details.

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 0%, so the description must compensate, and it documents all five params: body as HTML, published as student visibility with default False, front_page as the home-page toggle, and course_id's CANVAS_DEFAULT_COURSE_ID fallback. title/body definitions are thin ('page title', 'page HTML'), but the rest adds real meaning beyond the bare schema.

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

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

States a specific verb+resource ('Create a wiki page') and immediately flags 'MUTATES the course', which cleanly separates it from the read-oriented siblings canvas_get_page and canvas_list_pages. An agent can identify it without opening the schema.

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

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

Usage is implied by the verb and the mutation warning, and it references canvas_get_page/canvas_update_page as downstream consumers of the returned url, but it never states when to choose this over alternatives or any exclusions/preconditions. Adequate but no explicit routing.

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 no annotations, the description carries the full behavioral burden. It usefully discloses that writes go to the server machine rather than the user's laptop, and it documents defaults for dest_dir and name. However, it omits overwrite behavior, directory-creation semantics, permission requirements, and error handling, leaving meaningful gaps for a file-writing operation.

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

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

The description is front-loaded with purpose, immediately follows with a critical caveat about write location, and then presents an Args section. Every sentence earns its place, with no redundancy or filler.

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

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

An output schema exists, so return values need not be explained. The description covers purpose, the key server-side write caveat, and all parameters. It misses minor operational details like overwrite behavior and error handling, but is largely complete for a download tool.

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

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

Schema description coverage is 0%, so the description must compensate entirely. It documents all three parameters with clear meaning: file_id as a numeric id sourced from canvas_list_files, dest_dir with its default resolution chain (CANVAS_DOWNLOAD_DIR or ./canvas-downloads), and name with its default (Canvas display name). This fully covers the schema gap.

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 one course file to local disk.' The scope 'one course file' implicitly distinguishes it from bulk-download siblings like canvas_download_submissions, and it references canvas_list_files as the source for file_id. However, it does not explicitly name an alternative or sibling to route to, so it falls short of a 5.

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

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

The description implies usage by noting file_id comes 'from canvas_list_files,' which is a useful prerequisite. But it offers no explicit when-to-use guidance versus alternatives like canvas_download_submissions or canvas_upload_file, and no when-not conditions.

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 no annotations, the description carries the full burden and does substantial work: it discloses that files are written to disk on the server, gives the exact path template, flags a FERPA data-egress concern, and advises cleanup. Missing permissions/auth requirements and failure behavior, which keeps it from a 5.

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

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

Front-loads the core action, then layers path format and the FERPA warning; every sentence contributes. The args block is standard and readable. Slightly long but no filler.

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

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

Given a filesystem-writing tool with four parameters, no annotations, and an output schema (so return values needn't be described), the description covers destination behavior, defaults, cap, and data-handling risk. Only auth/permission expectations are absent.

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

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

Schema coverage is 0%, so the description must compensate and largely does: it documents assignment_id, dest_dir (with defaults CANVAS_DOWNLOAD_DIR / ./canvas-downloads), course_id (default CANVAS_DEFAULT_COURSE_ID), and max_files (safety cap, default 100). Minor mismatch in that it calls assignment_id numeric while the schema types it as string, and it doesn't explain the env-var resolution order fully.

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 with explicit scope: downloads EVERY file attachment for an assignment into a local folder. This is immediately distinguishable from canvas_download_file (single file) and canvas_list_submissions (enumeration only) without opening any schema.

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

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

The scope wording ('every file attachment for an assignment') implies the bulk-download use case and the FERPA note sets operational context, but the description never names alternatives or states when NOT to use it (e.g., use canvas_download_file for a single file, canvas_list_submissions to preview). Usage is inferable rather than explicit.

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

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

With no annotations, the description carries the full behavioral burden and does well: it warns the roster is mutated, clarifies the default invite-and-accept flow versus direct activation, and explains that no email is sent unless notify is requested. It stops short of stating auth/permission requirements or idempotency/reversibility of enrollment.

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 purpose and mutation warning are front-loaded, then defaults, then per-argument detail. It is somewhat long, but each sentence adds usable information and there is no filler.

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

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

For a mutation tool with no annotations and an output schema already present, the description supplies the missing safety/behavior context and full parameter semantics. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate and it does: every one of the six parameters is documented with meaning, including the 'sis_user_id:ABC123' alternate format, the allowed enrollment_type values, the invited/active distinction, and the env-var default for course_id.

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

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

States a specific verb and resource ('Enrol a user in the course') and immediately flags the side-effect profile ('MUTATES the roster'), which cleanly separates it from the read-only siblings like canvas_list_enrollments and canvas_list_students.

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 default behavior (state=invited, notify=False) and tells the agent when to deviate ('Pass enrollment_state="active" to place them straight onto the roster'). It also gives real-world context for SIS ids, but never explicitly names an alternative tool or states when NOT to use it.

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

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

With no annotations, the description carries the full disclosure burden. It usefully notes the plain-text rendering and the max_chars payload bound, and 'Get' implies a read operation, but it omits auth/permission requirements and error behavior (e.g., missing assignment or unauthorized course).

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

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

Front-loads the core purpose in the first sentence, then lists parameters compactly in an Args block. No filler; every line supports invocation.

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

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

An output schema exists, so return-value detail is not needed, and the max_chars bound is covered. However, for a no-annotation tool the description should also address read-only nature and failure modes, which it does not.

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 0%, so the description must compensate and largely does: it documents all three params, clarifies course_id falls back to CANVAS_DEFAULT_COURSE_ID, and explains max_chars=0 means the server default — semantics not present in the raw schema.

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

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

States a specific verb+resource ('Get one assignment') and adds a distinct behavioral note that the description is rendered to plain text. The singular 'one' implicitly differentiates it from canvas_list_assignments, though no sibling is named explicitly.

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

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

Usage is only implied: the required assignment_id signals it is for fetching a single known assignment. There is no explicit when-to-use vs when-not guidance, no mention of alternatives like canvas_list_assignments, and no prerequisites called out.

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?

No annotations are provided, so the description carries the full burden. It discloses the returned fields and that max_chars bounds the payload, which is helpful, but it omits auth/permission requirements and whether the call is strictly read-only (only implied by 'Get'). Adequate but incomplete for a zero-annotation tool.

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

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

One summary sentence plus a compact args block; the purpose is front-loaded and each line earns its place. Minor redundancy in restating the two parameters already in the schema, but no filler.

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

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

An output schema exists so return values needn't be detailed, yet the description still names the key contents. Both parameters are covered and the default-course fallback is called out; the only real gap is the lack of any permission/authentication note for a tool with no 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 coverage is 0%, so the description must compensate, and it does: course_id is explained as a numeric id from the course URL with a documented fallback to CANVAS_DEFAULT_COURSE_ID, and max_chars is described as a payload bound where 0 means the server default. That resolves both parameters, though it doesn't reconcile the string type in the schema with the 'numeric id' wording.

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

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

States a specific verb and resource ('Get one course') and enumerates the returned payload (teachers, student count, syllabus as plain text), which separates it cleanly from canvas_list_courses and canvas_get_gradebook. An agent can identify the tool without opening the schema.

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

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

The singular 'one course' plus the required course_id implies the use case (fetch a single course by id), and the fallback to CANVAS_DEFAULT_COURSE_ID is useful context. However, there is no explicit when-to-use vs. when-not guidance and no named alternative such as canvas_list_courses for multi-course retrieval.

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 no annotations, the description carries the full burden and does meaningful work: it discloses the return shape (full reply thread, plain text), a FERPA/attribution constraint, and payload bounding via max_chars. It omits auth/permission requirements and failure modes, which keeps it short of a 5.

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

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

Purpose is front-loaded in the first sentence, followed by a compact compliance/usage note and a tight Args block. Every line adds information (format, constraint, defaults) with no filler.

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

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

An output schema exists, so return values need not be re-explained; instead the description covers the format, privacy handling, default resolution, and payload bounding. For a 3-param read tool with no annotations, nothing essential is missing.

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

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

Schema description coverage is 0%, so the description must compensate and does: topic_id is the numeric discussion topic id, course_id defaults to CANVAS_DEFAULT_COURSE_ID, and max_chars bounds the payload with 0 meaning the server default. All three parameters gain semantics beyond their bare types.

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 ('Get a discussion topic with its full reply thread as plain text'), clearly distinguishing it from sibling listers like canvas_list_discussions and bulk exporters like canvas_download_submissions. An agent can tell what it fetches and in what shape without opening the schema.

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

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

Explicitly scopes usage ('summarise a week's discussion, not to bulk-export it'), giving both a use case and an exclusion. It does not name the specific alternative tool (e.g. canvas_list_discussions or a bulk export path), so routing is implied rather than explicit.

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

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

No annotations are provided, so the description carries the full burden and does reasonably well: it flags the FERPA sensitivity of returning a full class record, discloses that max_chars bounds the payload, and explains the single-call performance trade-off. It does not explicitly state the operation is read-only or note any auth/permission prerequisites.

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

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

Front-loads the core purpose in one sentence, follows with usage triggers and the FERPA warning, then an Args block. Every sentence adds information and nothing is padded.

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

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

An output schema exists, so return values need not be described, and the description covers usage, parameters, and sensitivity. The remaining gap is the lack of any explicit read-only/permission statement for a tool that returns an entire class record.

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 0%, yet the Args block documents all four parameters with real semantics: course_id is numeric and falls back to CANVAS_DEFAULT_COURSE_ID, assignment_ids is comma-separated with empty meaning all, include_names controls row labels, and max_chars is a payload bound where 0 means the server default.

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 ('Get the whole gradebook') and defines the return shape as a student-by-assignment table. It explicitly distinguishes itself from canvas_list_submissions by framing itself as one call instead of N, so an agent can route without opening either schema.

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

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

Gives concrete when-to-use triggers (find missing work, spot an assignment nobody passed, summarise standing before office hours) and names the alternative (canvas_list_submissions) it replaces. It stops short of stating when the per-submission tool is still preferable, e.g. for a single assignment.

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?

No annotations are provided, so the description carries the full burden. It does disclose two useful traits: the body is returned as plain text (not HTML) and max_chars bounds the payload with 0 meaning the server default. However, it says nothing about auth requirements, whether missing pages error or return empty, or whether the content is truncated silently.

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

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

One sentence of purpose followed by a tight per-argument list. No filler, and the essential return-format fact 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?

With an output schema present, return values need limited explanation, and the three parameters are all documented. The remaining gap is behavioral rather than structural: truncation semantics for max_chars and failure behavior for an invalid slug are unstated on a tool with no annotations to fall back on.

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 0%, so the description must compensate, and it does: page_url is defined as a url slug plus its source tool, course_id is a numeric id with its default env var named, and max_chars is defined as a payload bound where 0 selects the server default. All three parameters gain meaning beyond the bare schema.

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

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

States a specific verb and resource ('Get one wiki page's body') and specifies the return format ('as plain text'), which immediately distinguishes it from canvas_list_pages, canvas_create_page, and canvas_update_page. An agent can identify the operation without opening the schema.

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

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

The parenthetical '(from canvas_list_pages)' establishes an explicit upstream workflow for obtaining the page_url, which is real routing guidance. It gives no exclusions or when-not conditions, but the context for correct use is clear enough.

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

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

With no annotations, the description carries the full burden and does well: it flags FERPA/privacy sensitivity for a named student's work, discloses that attachments are listed but not inlined, and explains the max_chars payload bound. Read-only nature is implied by 'Get' but not explicitly stated.

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

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

Purpose and FERPA caveat are front-loaded, and the Args block is scannable. Every line contributes, though the prose plus arg list is slightly longer than strictly necessary for a four-parameter read tool.

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

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

Output schema exists so return values needn't be explained; the description covers purpose, privacy constraints, attachment behavior, the sibling alternative, and all parameters. An agent has everything needed 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 0%, so the description must compensate, and it does: all four params are documented with types and meaning (numeric ids, user_id accepting 'self', course_id defaulting to CANVAS_DEFAULT_COURSE_ID, max_chars with 0 = server default). This meaning is entirely absent from the schema.

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

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

States a specific verb and resource ('Get one student's submission') and enumerates exactly what is returned (body text, attachments, comments). It is clearly distinguishable from canvas_list_submissions (plural, list-level) and canvas_download_submissions (which it explicitly routes file fetching to).

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 names the alternative tool for a key case: 'attachment contents are not inlined, only listed; use canvas_download_submissions to fetch the files themselves.' This is clear routing guidance, though it doesn't contrast against canvas_list_submissions for the broader-list use case.

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

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

With no annotations present, the description carries the full behavioral burden and does so well: 'MUTATES STUDENT RECORDS', writes to the live gradebook immediately, and cannot be undone from here. It also discloses that the comment is visible to the student and that course_id defaults to CANVAS_DEFAULT_COURSE_ID.

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

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

Front-loads the destructive warning before the mechanics, then organizes parameters in a clean Args block. Given 0% schema coverage, every line of the parameter documentation 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?

An output schema exists, so return values need not be explained. For a six-parameter mutation tool with no annotations, the description covers safety, side effects, defaults, and every argument's semantics — nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: all six parameters are documented, including grade formats ('18', '88%', letter), the omit-to-comment-only behavior, excused semantics, and the course_id default. This adds substantial meaning beyond the bare schema titles.

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 ('Post a grade and/or a comment to a submission') that an agent can act on immediately. It does not, however, differentiate itself from the sibling canvas_bulk_grade, which an agent must disambiguate against.

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

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

Gives clear operating conditions: always show the instructor the exact student/assignment/grade/comment and get an explicit go-ahead, and never call it to 'try' something. Strong guidance, but it covers confirmation workflow rather than when to choose this tool over canvas_bulk_grade.

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 no annotations, the description carries the full behavioral burden, but it does disclose two useful traits: results are ordered most-recent-first and max_chars bounds the returned payload. It says nothing about pagination, permissions/authentication, or scope beyond the course, so coverage is partial.

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 purpose sentence is front-loaded and tight, and the Args block documents each parameter compactly. No filler sentences.

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

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

An output schema exists, so return structure need not be re-explained, and both parameters plus their defaults are covered. For a simple two-parameter listing tool this is nearly sufficient, lacking only failure/auth context.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: course_id is described as numeric and defaulting to CANVAS_DEFAULT_COURSE_ID, and max_chars as a payload bound where 0 means the server default. Only the exact units/behavior of max_chars truncation remain unspecified.

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

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

The description gives a specific verb and resource ('List a course's announcements'), plus ordering ('most recent first') and payload contents ('with their text'). It is clearly distinguishable from the write-side sibling canvas_post_announcement, though it does not call that sibling out by name.

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 explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. Usage is only implied by the verb 'List' versus the create/post siblings in the toolset.

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?

No annotations are provided, so the description carries the full burden. It discloses a valuable behavioral fact (weights are attached to groups, not assignments), which is real added context. However it says nothing about permissions, pagination, or the read-only nature beyond the implicit 'List', leaving gaps for a no-annotation tool.

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

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

Front-loaded with the core purpose, then rationale, then args. The Args block is slightly redundant with the schema but earns its place given 0% schema coverage. No wasted sentences.

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

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

An output schema exists, so return values needn't be explained, and the lone parameter is covered. For a simple read tool this is nearly complete; only minor behavioral detail (auth/permissions) is absent.

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

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

Schema description coverage is 0% and the single parameter has no schema-level documentation. The description compensates by describing course_id as a 'numeric course id' and documenting the default-to-CANVAS_DEFAULT_COURSE_ID behavior, which the schema does not convey.

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 ('List assignment groups') plus the salient attribute it returns ('their gradebook weights'). The second sentence clarifies the domain distinction from sibling tools like canvas_get_gradebook and canvas_list_assignments by explaining where weights actually live.

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 a clear directive: 'Read this before reasoning about what a score is worth.' That establishes the context in which the tool is needed. It does not name explicit alternatives (e.g. canvas_get_gradebook) or exclusions, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden. 'List' plus the enumerated read-only filters make the read-only nature clear and the default course fallback is disclosed, but there is no mention of permissions, pagination, or result limits for what may be a large collection.

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 summary sentence is front-loaded and each argument line earns its place given the empty schema. The multi-line bucket enumeration is slightly bulky but justified because those values exist nowhere else.

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, zero-required-parameter tool with an output schema already describing return values, the description covers the essentials: scope, defaults, and filter semantics. Only the absence of pagination/volume expectations keeps it from being fully complete.

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

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

Schema description coverage is 0% and the schema gives bucket as an untyped string with no enum, so the description does all the work: it names the default for course_id, enumerates all seven legal bucket values, and defines search_term as a title substring filter. This fully compensates for the schema gap.

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 ('List assignments in a course') and adds the salient payload ('due dates and needs-grading counts'), so the agent knows exactly what comes back. It does not explicitly contrast itself with siblings like canvas_get_assignment (singular fetch) or canvas_list_submissions, so it falls short of a 5.

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

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

Usage is implied rather than stated: the agent can infer this is the collection-level lister and that course_id falls back to CANVAS_DEFAULT_COURSE_ID. No explicit when-to-use/when-not guidance or named alternative is given, so it stays at the minimum-viable level.

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

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

No annotations are provided, so the description carries the burden; 'List' implies a read-only operation but this is never stated. It does add genuinely useful behavioral detail — that an empty start_date falls back to Canvas's default window — but omits pagination, rate limits, and permission 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 one-line purpose is front-loaded before the Args block, and each parameter line adds distinct information without redundancy. The formatting is terse and 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?

An output schema exists, so return values need not be explained. Combined with full parameter documentation and the default-window note, the description gives an agent enough to call the tool correctly; only pagination/return-volume expectations are unaddressed.

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

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

Schema description coverage is 0%, yet the description documents all four parameters: course_id defaults to CANVAS_DEFAULT_COURSE_ID, start_date/end_date use YYYY-MM-DD format, and include_assignments pulls in due dates. This compensates well for the empty schema descriptions, though it could clarify the default date window size.

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 ('List calendar events') and scopes it to a course, with an optional expansion ('and optionally assignment due dates'). It is clearly distinguishable from canvas_create_calendar_event and canvas_list_assignments by implication, though it never names a sibling explicitly.

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

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

Usage is implied by the scope ('for a course') and the include_assignments flag suggests the assignment-due-date alternative, but there is no explicit when-to-use guidance or statement of when to prefer canvas_list_assignments or canvas_get_assignment instead.

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 no annotations, the description carries the full behavioral burden. It discloses that results are auth-scoped to the caller's visibility and that output ids are the universal course identifier, which is useful context. However, it says nothing about pagination, result volume, read-only safety, or what happens with an invalid enrollment_state 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?

Front-loads purpose, then the 'start here' guidance, then the args — a sensible ordering with no filler sentences. The multiline Args block is slightly loose but every line carries required 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 two-parameter, zero-required list tool with an output schema, the description supplies what the structured fields lack: allowed values for both filters and the downstream significance of the returned id. Return shape is correctly left to the output schema, so nothing essential is missing.

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

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

Schema description coverage is 0%, so the description must do all the work, and it does: it enumerates enrollment_state values with the default (active, completed, invited_or_pending) and enrollment_type values by role (teacher, ta, student, observer, designer) plus the empty-for-all semantics. Case/syntax and combined-filter behavior are still unspecified, keeping it out of the top band.

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 ('List the courses') and immediately qualifies scope ('the authenticated user can see'). It further orients the agent relative to siblings by declaring itself the entry point when the course id is unknown, so it is distinguishable from canvas_get_course and the many course_id-consuming 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?

Explicitly says 'Start here when you do not know the course id' and explains that the returned id feeds every other tool's course_id parameter, which is genuine routing guidance. It stops short of naming a specific alternative tool or stating when not to use it (e.g. if the id is already known, use canvas_get_course).

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 no annotations, the description carries the full behavioral burden but only states the scope. It says nothing about pagination, result limits, ordering, or required permissions — notable gaps for a list operation. It does disclose the CANVAS_DEFAULT_COURSE_ID fallback, which is the one piece of added 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?

Very short and front-loaded, with the core purpose in the first sentence. The 'Args:' block is somewhat redundant with the schema but not wasteful.

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

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

An output schema exists so return values needn't be explained, and the single parameter is covered. But as a list tool with no annotations, it omits pagination and result-set behavior, leaving meaningful gaps 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 0% and the schema default is an empty string, so the description adds real value by explaining that course_id is numeric and falls back to CANVAS_DEFAULT_COURSE_ID. With a single parameter, this adequately compensates for the schema gap.

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 ('List discussion topics in a course'), which naturally distinguishes it from canvas_get_discussion and canvas_create_discussion. However, it does not explicitly name those siblings or clarify the boundary (e.g. list all vs. fetch one).

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 when-to-use guidance, prerequisites, or alternatives are given. The agent must infer that this is the bulk-retrieval counterpart to canvas_get_discussion from the verb 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses a critical downstream dependency (enrollment_id is required to modify enrollments) and a dangerous silent-failure mode, which is high-value context beyond the schema. It does not cover pagination, return shape, or auth, but the failure-mode warning is the most important behavioral trait here.

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

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

Three short paragraphs: purpose and key distinction first, the failure-mode warning second, then a clean Args block. Every sentence earns its place and the most decision-relevant information 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 3-param, 0%-documented-schema tool with no annotations, the description supplies the role/state enumerations, the default resolution behavior, the sibling distinction, and the downstream dependency. An output schema exists, so return values need not be explained. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does: course_id is documented as numeric with a default fallback to CANVAS_DEFAULT_COURSE_ID, role enumerates the exact accepted values, and state enumerates its values with the empty-string semantics for 'all'. Without this, the schema fields are opaque strings.

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 ('List enrollments') and immediately clarifies the critical distinction from its sibling canvas_list_students: enrollments are not users, and the enrollment_id is a different number from the user id. This is exactly the kind of disambiguation that helps an agent select the right tool.

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

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

It gives explicit when-to-use guidance ('Fetch it here first') and a concrete when-not-to / failure mode ('passing a user id to canvas_remove_enrollment silently targets the wrong record or 404s'). It names the alternative tool (canvas_list_students) and explains why the agent should prefer this one for the mutation workflow.

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 no annotations, the description carries the full burden, and it does disclose two useful behaviors: course_id defaults to CANVAS_DEFAULT_COURSE_ID and search_term requires 3+ characters. However, it omits permission requirements, pagination/result-limit behavior, and any explicit read-only confirmation beyond the verb 'List'.

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 purpose is front-loaded in the first sentence and the argument notes follow compactly with no wasted prose. The 'Args:' formatting is slightly mechanical but not 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?

An output schema exists, so return values need not be described, and both parameters are covered. Still, for a list tool with no annotations it leaves unresolved how many results return, whether pagination applies, and what permissions are needed, leaving a moderate 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 0%, so the description must compensate, and it does: it documents both parameters, notes course_id is numeric and defaultable, and characterizes search_term as an optional filename substring filter with a 3+ character constraint. This adds real meaning beyond the bare schema types, though it could specify filter behavior more precisely.

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 ('List files uploaded to a course'), which is clearly distinct from write-oriented siblings like canvas_upload_file or canvas_download_file. It does not explicitly name or differentiate against those siblings, but the core purpose 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?

There is no guidance on when to use this versus alternatives such as canvas_download_file (retrieve one file) or canvas_upload_file. Usage must be inferred entirely from the tool name, with no prerequisites or exclusions 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?

No annotations are provided, so the description carries the full burden. It does disclose the with_items inlining behavior and that max_chars bounds the returned payload (0 = server default), which is real behavioral context beyond the schema. However, it says nothing about permissions, pagination limits, or error conditions for an otherwise straightforward read tool.

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

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

Front-loaded with the core purpose in the first line, followed by a single value-adding sentence and a compact Args block. No wasted prose; slightly more could have been trimmed but the structure is clean.

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

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

An output schema exists, so return-format explanation is unnecessary, and all parameters are documented. The remaining gap is usage routing against siblings and any permission context, minor for a read-only listing tool.

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

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

Schema description coverage is 0%, so the Args block does all the work — and it succeeds: course_id is explained as numeric with a CANVAS_DEFAULT_COURSE_ID fallback, with_items as inlining items with a default, and max_chars as a payload bound with 0 meaning the server default. All three parameters are semantically documented.

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 ('List course modules') and frames the result as 'the course outline,' which distinguishes it from the many other list_* siblings targeting assignments, pages, quizzes, etc. It stops short of explicitly naming which sibling to prefer, so not a full 5.

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

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

The phrase 'the fastest way to see how a course is actually structured week by week' implies when this tool is useful, but there is no explicit when-to-use/when-not guidance or named alternative (e.g., versus canvas_list_assignments or canvas_get_course). Usage 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?

No annotations are provided, so the description carries the burden. It discloses a real behavioral trait beyond the schema: that the returned `url` is the slug the other page tools consume, not page_id or a full URL. It still doesn't state pagination behavior or permissions, but output schema exists to cover returns.

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 tight lead sentence that front-loads purpose and payload scope, followed by the single most important caveat (the url vs page_id trap). Every sentence earns its place.

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

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

For a two-param read tool with an output schema, the description covers purpose, both parameters, and the critical returned-field gotcha. Only explicit sibling routing and pagination semantics are absent.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: course_id is a numeric id defaulting to CANVAS_DEFAULT_COURSE_ID, and search_term is a title substring filter. This exceeds what the bare 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?

States a specific verb+resource ('List wiki pages in a course') and immediately scopes the payload ('titles and url slugs, not bodies'). This distinguishes it from canvas_get_page, which fetches a body.

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 (course-scoped wiki page listing) with the 'not bodies' exclusion implying the agent should use get_page for content. It does not explicitly name canvas_get_page as the alternative, so it falls short of a full 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?

No annotations are present, so the description carries the full burden; it discloses an important domain quirk (New Quizzes surface as assignments with submission_type=external_tool), which is genuine behavioral context. It stops short of covering read-only nature, pagination, or result limits, so it is strong but not complete for an unannotated tool.

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

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

The purpose is front-loaded in one line, the routing caveat follows immediately, and the Args block is terse. Every sentence carries information an agent needs; there is no filler.

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

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

An output schema exists, so return values need not be described, and the one parameter is covered. The remaining risk for this tool is the Classic-vs-New-Quizzes confusion, which the description addresses head-on.

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 0%, so the description must compensate, and it does: it specifies the parameter is numeric and that it defaults to CANVAS_DEFAULT_COURSE_ID when omitted, matching the empty-string default in the schema. This fully documents the single parameter, though it adds no format/validation detail beyond that.

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

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

States a specific verb+resource ('List quizzes in a course') and goes further to scope which quiz system it covers (Classic Quizzes) and what it excludes. An agent can distinguish it from canvas_list_assignments and canvas_list_discussions without opening any schema.

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

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

Explicitly states when to use this tool and what to do when it returns nothing ('check canvas_list_assignments if a quiz you expect is missing'), naming the concrete alternative. This is a real when/when-not/alternative rule, not implied guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that enrollment counts accompany each section and that the call is a listing operation, but says nothing about permission requirements (e.g., teacher/admin vs student visibility) or pagination, which matters for a roster-scoped read.

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

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

Front-loads the purpose in one sentence, then a short scoping paragraph, then an Args block. Every element earns its place, though the middle paragraph is slightly verbose for a simple list tool.

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

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

An output schema exists, so return values need not be described, and the single parameter plus its default environment fallback is documented. For a one-param read-only tool this is nearly complete; only permission/visibility expectations are unstated.

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 0%, so the description must compensate, and it does: it explains that course_id is a numeric course id and, critically, that it defaults to CANVAS_DEFAULT_COURSE_ID — a behavior invisible in the schema's empty default string. It doesn't clarify format beyond 'numeric' (e.g., leading zeros, course vs section ids).

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

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

States a specific verb and resource — 'List a course's sections' — and adds that enrollment counts are returned, which is concrete. It clearly reads as distinct from course-level tools like canvas_get_course or canvas_list_enrollments, though it never names a sibling to route against.

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 middle paragraph gives real context for when sections matter: section-level due dates, lab subsections, and enrolling into a specific section 'rather than the course default.' That is genuine when-to-use guidance, though it offers no explicit exclusions or named alternative 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?

No annotations are provided, so the description carries the full burden and does so well: it discloses FERPA-relevant output (names, conditional emails) and the CANVAS_REDACT_PII=1 hashing behavior, which an agent cannot derive from the schema. It omits pagination behavior and permission requirements, keeping it short of a 5.

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

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

Front-loaded with the purpose, then a compact FERPA note, then an Args block that maps one line per parameter. No filler sentences; the formatting is slightly rough but 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?

An output schema exists, so return values need not be described, and the description covers the non-obvious behavior (PII redaction, defaults, filter constraints). Missing pagination and result-limit context is the only real 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 0%, so the description must compensate, and it does: it documents all three parameters, including the CANVAS_DEFAULT_COURSE_ID fallback and the 3-character minimum on search_term. It stops short of clarifying that course_id is a string field.

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

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

States a specific verb+resource: 'List the students enrolled in a course.' An agent immediately knows the operation and scope. However, it does not distinguish itself from the nearby sibling canvas_list_enrollments, which plausibly overlaps in purpose.

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 says nothing about when to use this tool versus alternatives such as canvas_list_enrollments or canvas_get_gradebook, nor any prerequisites beyond the default course id. Usage must be inferred 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the metadata-only scope and the semantics of the filter flags, but says nothing about permissions, pagination, or rate limits. Output schema presumably covers the return shape, which keeps this at an adequate rather than weak level.

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

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

Front-loaded purpose sentence, one routing sentence, then a compact Args block; every line earns its place given 0% schema coverage. Minor redundancy exists only because the Args block repeats parameter names already in the schema, which is justified here.

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

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

An output schema exists so return values need not be described, and the metadata-only framing plus full parameter semantics make the definition callable as written. Missing pagination and permission behavior keep it from being fully complete for a list endpoint.

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 0%, so the description must compensate, and it does: all four parameters are explained in the Args block, including the fallback to CANVAS_DEFAULT_COURSE_ID and the meaning of include_ungraded. It omits stating only_submitted's default, which the schema sets to false, leaving a small gap.

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 ('List') and resource ('submissions for an assignment') and enumerates the returned fields (status, score, timestamps, lateness). It explicitly distinguishes itself from the sibling canvas_get_submission by declaring it is metadata only, so an agent can route correctly without opening any schema.

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

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

Gives a clear when-not: use canvas_get_submission for a student's actual work, implying this tool is for roster-level status views. It does not address other plausible siblings (canvas_download_submissions, canvas_get_gradebook), so it stops short of full alternative routing.

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?

No annotations exist, so the description carries the full burden and does so well: it discloses irreversibility ('cannot be recalled'), that it actively notifies recipients, the privacy implication of the default per-recipient threading, and the disclosure risk of group threads. These are exactly the behavioral traits an agent needs before mutating state.

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

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

Front-loaded with the action and the highest-stakes warning ('NOTIFIES PEOPLE'), followed by usage rules and then parameter notes. Every sentence adds information the schema does not already carry; nothing is padding.

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

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

An output schema exists, so return values need no explanation here. Combined with the parameter notes and the approval/privacy guidance, an agent has everything required to invoke this correctly and safely.

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 0%, yet every parameter is explained: recipient_ids accepts a comma-separated list or JSON array, group_conversation controls thread sharing with a stated default, and course_id's scoping effect and fallback to CANVAS_DEFAULT_COURSE_ID are spelled out. This fully compensates for the absent schema descriptions.

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

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

States a specific verb and resource ('Send a Canvas inbox message to one or more students'), cleanly distinguishing it from sibling announcement and discussion tools. An agent can tell immediately this is direct messaging, not a public post.

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

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

Gives explicit when/when-not guidance for group_conversation ('only pass group_conversation=True when students are meant to see each other') and a required approval workflow before every send. It stops short of naming a sibling alternative (e.g. post_announcement) for the broadcast case, but the operating conditions are 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?

No annotations exist, so the description carries the full behavioral burden and does so well: it discloses the mutation, that students are notified, that Canvas emails the whole roster, and the irreversible consequence ('deleting the announcement afterwards does not unsend it'). This is exactly the destructive/irreversible context an agent needs before calling.

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

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

Front-loads the mutation warning in bold, then the approval requirement, then the scheduling alternative, then parameter notes. Every sentence adds decision-relevant information with no filler.

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

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

Covers the safety-critical behavior, the approval workflow, the scheduling option, and all four parameters. An output schema exists, so return values need not be described, leaving nothing an agent needs missing.

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

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

Schema description coverage is 0%, yet the description documents every parameter: title as subject line, message as body with HTML allowed, delayed_post_at as ISO 8601 UTC publish time, course_id as numeric id defaulting to CANVAS_DEFAULT_COURSE_ID. It fully compensates for the schema gap.

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

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

States a specific verb+resource (post an announcement) and immediately characterizes what it does to the system: 'MUTATES the course — students are notified.' An agent can distinguish this from the sibling read tool canvas_list_announcements without opening the schema.

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

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

Gives explicit pre-call workflow ('Show the instructor the exact title and body and get explicit approval') and an alternative mode (pass delayed_post_at to schedule instead of posting immediately). It stops short of routing the agent between this and other notifying siblings like canvas_message_students, so it is clear context rather than full when/when-not/alternatives guidance.

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

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

With no annotations supplied, the description carries the full burden and does well: it declares the mutation, the leave-alone semantics for omitted fields, and two non-obvious side effects (publishing unseen assignments, silently re-scaling graded scores when points_possible changes). It does not cover auth requirements or whether edits are reversible.

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

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

Front-loads the mutation and the downstream-effect warnings before the args list, and every line of the args block earns its place. The repeated 'or empty to leave unchanged' phrasing is slightly redundant but does encode per-field semantics rather than 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 10-parameter mutation tool with no annotations, an output schema (so returns need no explanation) and full parameter documentation, this is nearly complete — side effects, defaults, and formats are all covered. Only authorization/error behavior is absent.

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

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

Schema description coverage is 0% across 10 parameters, so the description must compensate fully — and it does. Each parameter is described with meaning beyond its type, including the crucial distinction between empty-string (leave unchanged) for name/description/due_at versus omit for points_possible/published, ISO 8601 UTC date formats, and the CANVAS_DEFAULT_COURSE_ID fallback.

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

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

States a specific verb+resource ('Edit an existing assignment') and immediately flags the mutation, which cleanly separates it from canvas_get_assignment and canvas_create_assignment in the sibling list. An agent can select it without further inference.

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 the partial-update contract ('only the fields you pass are changed; omitted ones are left alone') and calls out two edits with downstream gradebook consequences worth warning an instructor about. It stops short of naming alternatives or stating explicit preconditions such as required permissions.

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

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

With no annotations, the description carries the full burden and does so well: it flags MUTATES, partial-update semantics, the immediate student visibility of publishing, and the Canvas restriction that a course cannot be unpublished after a student submits work. These are exactly the side effects an agent must know before calling.

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

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

The critical warnings are front-loaded in the first sentence, and the Args block earns its place because the schema has no property descriptions. It is slightly list-like and repeats property names, but there is little wasted text.

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

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

For a 7-param mutation tool, it covers behavior, side effects, field semantics, and per-parameter formats; an output schema exists, so return values need not be explained. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 0%, and the description compensates by documenting all seven parameters: empty-string means leave unchanged, start_at/end_at are ISO 8601 UTC with an example, published accepts True/False/omit, default_view lists the allowed landing pages, and course_id notes its default. This is meaningful added semantics beyond the bare schema.

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

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

States a specific verb+resource ("Edit course settings") and immediately scopes it as a live mutation, which cleanly separates it from read siblings like canvas_get_course and canvas_list_courses. An agent can tell what this does without opening the schema.

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

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

Gives clear operational context — only passed fields change, and it advises confirming before setting published=True because publishing is immediately visible and hard to reverse. It never names an alternative tool (e.g., canvas_update_syllabus) or an explicit when-not-to-use, so it falls short of the top band.

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 no annotations, the description carries the full burden and does well: it warns of mutation, discloses the cascading side effect on module items, and states that omitted fields are left unchanged. It omits permission/auth requirements and rate-limit behavior, which keeps it from a 5.

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

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

Front-loads the mutation warning and cascade behavior before the Args block, which is exactly what an agent needs first. The Args list is slightly verbose but every line adds information about defaults and no-op semantics.

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

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

An output schema exists, so return values need no explanation. The description covers mutation, cascade, partial-update semantics, and all parameters. The only material gap for a mutating tool with no annotations is permission/auth context.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents all five parameters: module_id, name (empty = unchanged), position (omit = unchanged, 1-based), published (omit = unchanged), and course_id (defaults to CANVAS_DEFAULT_COURSE_ID). Each parameter gains meaning not present in the bare schema.

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

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

States a specific verb and resource ('Edit or publish a module') and immediately flags that it mutates the course. An agent can distinguish it from create_module and list_modules by the verb. It stops short of naming a sibling, but the scope 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?

Explains the key usage context: publishing a module also publishes its items, which is how a week's content goes live. It also clarifies partial-update semantics ('Only the fields you pass change'). No explicit when-not or alternative tool is named, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and mostly meets it: it discloses that only passed fields change, that body REPLACES the whole page, that HTML formatting is flattened on round-trip through canvas_get_page, and that renaming preserves the url slug. It stops short of stating permission requirements, failure modes, or whether edits are reversible, which keeps it from a 5.

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

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

Front-loads the verb, resource, and mutation warning, then organizes per-parameter detail under an Args block. Each sentence carries actionable information with no filler.

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

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

An output schema exists so return values need not be described, and the mutation/HTML-flattening caveats cover the riskiest behavior. Minor gaps remain around required permissions and error conditions for a write tool with zero annotation coverage, but nothing essential for a correct call is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: page_url is a slug not an id, title/body empty means unchanged, published omitted means leave alone, and course_id defaults to CANVAS_DEFAULT_COURSE_ID. Every parameter's sentinel/empty semantics are explained beyond the bare types in the schema.

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

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

States a specific verb and resource ('Edit a wiki page') and immediately flags the mutation ('MUTATES the course'). An agent can distinguish it from canvas_get_page, canvas_create_page, and canvas_list_pages without opening any schema.

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

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

Names concrete alternatives with selecting conditions: 'read canvas_get_page first if you mean to append' and points to canvas_list_pages as the source of the required page_url slug. This is explicit when-to-use and when-to-use-something-else guidance rather than 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?

With no annotations, the description carries the full burden and does so well: it discloses wholesale overwrite, absence of version history, the recommended read-before-write workflow, and the non-obvious newline-to-<br> formatting behavior.

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

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

The destructive warning is front-loaded ahead of the argument docs, and every sentence adds information. The 'Args:' block is slightly verbose but still earns its place given zero schema coverage.

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

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

An output schema exists, so return values need not be described; the description covers the destructive semantics, prerequisites, and both parameters. The main remaining gap is the auth/permission requirement for writing to a live course page.

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 0%, so the description must compensate, and it does: 'body' is explained as HTML with a caveat that plain newlines are not converted, and 'course_id' is documented as defaulting to CANVAS_DEFAULT_COURSE_ID. Only the accepted format/validation of course_id is left implicit.

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

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

States a specific verb+resource ('Replace the course syllabus body') and immediately flags the mutation ('MUTATES the live course page'), which distinguishes it from read siblings like canvas_get_course and from the broader canvas_update_course.

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

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

Explicitly tells the agent to read canvas_get_course first when current text matters and to show the instructor what is being replaced. Strong precondition guidance, though it doesn't contrast against any near-alternative (there is no sibling that also edits the syllabus).

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 no annotations, the description carries the full burden and does well: it declares the mutation, discloses the three-step upload flow (register, POST bytes, confirm), and adds a real security detail that the Canvas token is never sent to the storage host. It stops short of stating auth requirements, reversibility of overwrite, or error/rate-limit behavior, so it is strong but not exhaustive.

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

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

Front-loads purpose and the mutation warning before the process note and Args list. The 'Three-step Canvas dance' phrasing is slightly informal but informative, and the Args block earns its space given the 0% schema coverage.

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

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

An output schema exists, so return values need not be explained. The description covers mutation semantics, the internal upload flow, security, and all parameters; only auth prerequisites and overwrite consequences are left implicit, 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 0%, so the description must compensate and it does — every parameter is documented with meaning beyond the bare schema: local_path is server-side absolute, parent_folder_path is a Canvas path auto-created if absent, name defaults to the local filename, on_duplicate distinguishes rename vs overwrite, and course_id falls back to CANVAS_DEFAULT_COURSE_ID.

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

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

States a specific verb and resource ('Upload a local file into the course's Files area') and flags the operation type with 'MUTATES the course.' This clearly separates it from read-only siblings like canvas_list_files and canvas_download_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 implies the usage context (pushing a local file into course Files) but never states when to choose this over alternatives such as canvas_download_file, nor any prerequisites or exclusions. Usage is inferable from purpose but not explicitly guided.

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