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

The annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the /api/v1 scope and an example path, but does not discuss auth requirements, pagination, error behavior, or rate limits. It adds some value beyond annotations without being rich behavioral guidance.

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

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

The description is two compact sentences: the purpose and scope are front-loaded, followed by a useful example path. There is no redundant or filler 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 an open-world raw GET tool with no output schema, the description gives enough to identify the endpoint pattern but omits the optional params usage and does not mention response shape, errors, or pagination. It is minimally adequate as an escape hatch but leaves meaningful gaps for an agent invoking arbitrary Canvas endpoints.

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 does clarify the required path parameter's scope and gives a concrete example, but it never explains the optional params object or how its entries map to query-string parameters.

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 (GET), resource (any Canvas REST endpoint under /api/v1), and framing (escape hatch, read-only). It clearly distinguishes this raw passthrough from the many specific canvas_* sibling 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?

Calling it an 'escape hatch' strongly implies use when no dedicated Canvas tool covers the endpoint, and the example clarifies the expected path form. It does not explicitly say to prefer sibling tools first, so it stops short of a full when/when-not/alternative rubric.

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

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

Annotations already declare read-only, non-destructive, closed-world, so the description's job is to add context — and it does: data comes from daily snapshots refreshed in the background when stale, results are grouped by course newest-first, and times are UTC. The staleness/freshness caveat is exactly the kind of thing annotations cannot convey.

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

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

Front-loaded with the core action, then progressively narrower details; every clause carries information. The first sentence is long and listing-heavy, but no sentence is 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?

With no output schema, the description does the work of describing returned content, field diffs, ordering, and grouping. Only the `course_id` scoping behavior is unaddressed, a minor gap for a 3-parameter read tool with 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?

At 67% schema coverage, the schema already documents `kinds` (with its value list) and `since`. The description reinforces the 26h default and UTC convention, but `course_id` is left unexplained in both the schema and the description, so it adds only modest value over structured fields.

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

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

Specific verb+resource: reports what changed across a well-enumerated set of Canvas object types (pages, assignments, announcements, discussions, quizzes, events, files). It also names the data source (stored snapshots) and scope (your courses), which separates it from static-state siblings like canvas_course_snapshot.

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 best first call for a daily check" plus the 26-hour default gives the agent a clear entry-point heuristic. It doesn't name alternatives or when-not to use it (e.g., vs canvas_whats_new or a full snapshot), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's one real addition is "no Canvas calls" — implying local cached reads — but it never says how stale the snapshot can be or how it relates to canvas_run_snapshot refreshing it, which is the key behavioral caveat for a cache-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?

Two sentences, zero filler, with the most decision-relevant fact ("no Canvas calls") and the compactness trade-off front-loaded. Every clause carries information the agent can act on.

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-parameter read tool with annotations present and no output schema, the description is serviceable but thin: it never characterizes the return shape beyond "compact", doesn't explain how text_chars truncation manifests, and doesn't mention staleness or how a snapshot is refreshed. An agent can call it, but not fully predict what it receives.

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 only 33% (text_chars alone is documented), so the description does real work: it enumerates the kinds vocabulary and gives a concrete example ("["assignment"] for all deadlines and grades") that explains intent, not just the allowed strings. It does not clarify course_id's expected format, which is the main remaining 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 resource and scope: the stored/cached state of one course from the latest snapshot, explicitly "(no Canvas calls)". This differentiates it from live-fetch siblings like canvas_list_assignments, though it never names those siblings directly, so the differentiation must be inferred from the parenthetical.

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 only guidance is about parameter usage ("Use kinds ... to keep it small"), not about when to choose this over canvas_list_assignments or canvas_run_snapshot. Nothing tells the agent when the cached snapshot is preferable (speed?) versus when freshness requires a live call.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful return context ('description as text' — i.e. HTML is converted, not raw), but says nothing about behavior when the assignment_id is invalid or belongs to another 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?

A single front-loaded sentence with zero filler. It is appropriately sized for a two-parameter read tool, though it could have spent one more clause on the alternative or parameter sourcing at no real cost.

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

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

For a simple read tool with annotations and no output schema, the description covers what is returned, but with 0% schema coverage it should also explain where course_id/assignment_id come from and what happens on an unknown ID. It is adequate but leaves the two required parameters opaque.

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 schema provides only bare names and types. The description adds no meaning: it doesn't say course_id is the Canvas course identifier obtained from canvas_list_courses, nor clarify the assignment_id format (integer ID vs slug). Both required parameters remain semantically undocumented.

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 resource (one assignment) and what it returns ('full details... including the description as text'), which implicitly contrasts with the sibling canvas_list_assignments. It never names the sibling or explicitly says 'single assignment by ID', so differentiation is inferred rather than stated.

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

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

The phrase 'of one assignment' hints that this is the single-item retrieval path versus listing, but there is no explicit when-to-use, no prerequisites (e.g. needing the course_id from canvas_list_courses first), and no named alternative such as canvas_list_assignments.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value by scoping results to the caller's own submissions and listing the fields returned, but it says nothing about behavior for a teacher/instructor account, empty-result behavior, or whether unpublished grades are included.

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

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

A single dense sentence that front-loads the scope ('Your own submissions in a course') before the field list. No filler, though the parenthetical placement slightly breaks the flow.

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

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

No output schema exists, and the description does a fair job of describing the return contents. But for a tool whose only input is course_id, the description leaves the parameter format and the student-only behavioral boundary (what happens for instructors) unexplained, which is a real gap for an agent composing the call.

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

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

There is one required parameter, course_id, with 0% schema description coverage, and the description never mentions it or its expected form (numeric ID vs. Canvas course code). With a single undocumented parameter the description needed to carry that weight and does not.

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

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

The description names a specific resource (the caller's own submissions in a course) and enumerates the payload fields — scores, grades, late/missing flags, teacher comments — which clearly separates it from canvas_list_assignments and canvas_get_assignment. It stops short of a verb phrase and never explicitly contrasts itself with the assignment tools, but the resource is unambiguous.

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

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

The parenthetical '(as a student)' implies the eligibility condition: this returns the caller's own grades, not a teacher's view of a roster. However, there is no explicit when-to-use statement, no mention of when this is the wrong tool (e.g. versus canvas_get_assignment for assignment metadata), and no prerequisites such as enrollment.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context about output shape: file links appear inline as (file:<id>) and are also listed in file_links, plus a hand-off to canvas_read_file. It says nothing about pagination, truncation of long pages, or errors on bad slugs.

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

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

Three short sentences, action first, then parameter sourcing, then output format. No filler and nothing buried at the end.

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

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

With no output schema, the description usefully sketches the return payload (text plus inline file references and a file_links list) and points to the follow-up tool. The remaining gap is the undocumented course_id parameter and no mention of error behavior for invalid slugs.

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 carry the load. It explains page_url well, including the 'front_page' sentinel which is a real semantic addition. course_id, however, is never described — the agent must infer it comes from canvas_list_courses — leaving half the parameters undocumented.

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: 'Read a course page as text.' The reference to using the page_url slug from canvas_list_pages/list_modules implicitly separates it from the listing sibling, though it never names an alternative tool for the 'fetch by id' niche 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?

Gives concrete guidance on how to obtain the page_url value (from canvas_list_pages or list_modules) and names the 'front_page' sentinel as a valid shortcut. It stops short of stating exclusions or failure conditions, but the routing context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one genuine behavioral fact — that results depend on whether the course uses the syllabus page, implying an empty/absent result is possible — but says nothing about the return format (plain text vs HTML) or error 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?

A single short sentence with no waste, and the key noun (syllabus text) is front-loaded. The trailing conditional is slightly awkward but earns its place as the only usage caveat.

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

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

For a simple one-parameter read tool with annotations and no output schema, the description covers what is returned and the conditional availability. It leaves gaps on course_id format and the shape of the returned text, which an agent needs to call and consume 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% for the single required course_id, so the schema carries no meaning and the description offers none either — it never mentions the parameter, its expected format, or that it identifies a Canvas course.

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

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

The description names a specific resource — the course syllabus / course overview text — which is clearly distinct from the sibling page/module/file tools. It lacks an explicit verb and never names an alternative, but an agent can tell what content this returns.

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 only guidance is the conditional 'if the course uses Canvas's syllabus page', which hints at possible absence but gives no when-to-use criteria and never contrasts with canvas_list_pages or canvas_get_page, the closest alternatives for course content.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavior (newest-first ordering, default course scope and 14-day window), but says nothing about result volume, pagination, or whether announcements are filtered by enrollment or publication 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?

Two compact fragments, zero filler, with the resource and ordering front-loaded before the defaults. Every clause 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 two-optional-param read-only list tool with full schema documentation and safety annotations, the description covers purpose, ordering, and defaults adequately. The only meaningful gap is result size/pagination behavior, which matters little for a small scoped read.

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

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

Schema coverage is 100% and both optional parameters are documented in-schema, so baseline 3 applies. The description's 'last 14 days' and 'all active courses' restate the schema defaults rather than adding new semantics about format or interaction between parameters.

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?

Names the specific resource (course announcements) and its ordering (newest first), which is enough to tell it apart from siblings like canvas_list_assignments or canvas_get_syllabus. It never uses an explicit verb like 'list', relying on the title for that, but the resource 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?

The default scope ('all active courses, last 14 days') implies when the tool is useful out of the box, but there is no explicit when-to-use or when-not-to-use guidance and no routing to alternatives such as canvas_whats_new or canvas_changes_since for recent-activity queries.

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

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

Annotations already establish that this is a read-only, non-destructive operation. The description adds only that results include due dates and submission status, but does not explain pagination, ordering, permission scope, or how the bucket filter changes results.

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

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

The description is a single front-loaded sentence with no wasted wording. It is appropriately sized for a simple listing tool, though brevity contributes to the missing usage and parameter detail.

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

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

For a simple read-only list tool with annotations and a mostly self-explanatory schema, the description is still incomplete. It omits the important bucket filtering behavior and any guidance on how this differs from getting a single assignment, leaving the agent to infer usage from the schema.

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

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

Schema coverage is 50%: the bucket parameter is described in the schema, while course_id has no description there. The tool description does not mention either parameter or clarify what the bucket values mean or how omission behaves, so it does not compensate for the coverage 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 clearly identifies the resource and scope: assignments in a specific course, including due dates and submission status. It does not explicitly state a verb or distinguish itself from sibling tools like canvas_get_assignment or canvas_list_planner_items, but the purpose is clear.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention canvas_get_assignment for a single assignment or canvas_list_planner_items for cross-course planning, nor does it explain when the bucket filters are appropriate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds a useful caveat that lectures/seminars/exams appear only if teachers added them, warning about possible incompleteness. It does not mention pagination, return format, or enrollment scoping.

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

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

The description is a single compact sentence with no wasted words, and the date-range constraint is front-loaded. It is efficient, though the noun-phrase style is slightly less direct than a verb-led description.

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

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

For a simple read-only tool, annotations cover safety and the schema covers date defaults. However, the description does not explain course_ids scope, output shape, or pagination, and there is no output schema to fill those gaps. It is minimally adequate but incomplete.

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

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

Schema coverage is 67%, with start_date and end_date documented as ISO strings with defaults. The description reinforces the date-range concept but does not explain course_ids filtering, which is undocumented in both schema and description. Baseline 3 is appropriate given partial schema coverage.

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

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

The description names the specific resource (Canvas calendar events) and scopes it to a date range, with examples of event types. It does not explicitly name the listing action, but the tool name supplies that. The resource is distinct from siblings, though no sibling is named for contrast.

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 guidance. It does not mention alternatives such as canvas_list_planner_items or canvas_list_assignments, nor does it state prerequisites. Usage is only implied by the resource and date-range phrase.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the non-obvious behavioral detail that completed courses are excluded unless requested and that role information comes back per course — context an agent would otherwise have to discover by trial. Pagination and rate-limit behavior remain undisclosed.

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

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

Two short sentences with zero filler; the default-scope fact and the downstream-use note are both front-loaded before any caller needs to decide.

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

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

With no output schema, the description does the necessary work of naming the returned fields (role per course, course ids). For a single-param read tool whose annotations cover the safety profile, that is nearly sufficient; only pagination/result-size behavior is 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 coverage is 100% and the single parameter documents itself ('Also include completed/past courses'), so the schema carries the load. 'Active by default' reinforces what that flag toggles but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('List your Canvas courses') plus the exact payload ('with your role in each'), which no sibling tool duplicates. It positions itself in the workflow by noting it returns course ids needed elsewhere, though it doesn't explicitly name the siblings that consume those ids.

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?

'Returns course ids needed by other tools' tells the agent this is the entry point for the rest of the course-scoped workflow, and 'active by default' flags that the default view is filtered. No explicit when-not case or named alternative is given, but nothing in the sibling set conflicts with it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, lowering the bar. The description does add real value by disclosing permission-dependent source switching (course index vs linked-content fallback, common for students) and default ordering, but says nothing about pagination, result limits, or what the returned records look like.

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

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

Two dense, front-loaded sentences with no filler — the resource and ordering come first. The trailing "like canvas_list_linked_files" clause is slightly awkward but carries genuine information about fallback behavior.

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

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

With no output schema and zero schema coverage on two parameters, the description should carry more weight. It covers the interesting behavioral wrinkle (role-based source selection) but leaves the search filter and returned fields entirely unaddressed, so an agent still has gaps before calling.

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 not. It never mentions the `search` parameter at all, leaving an agent to guess at its filtering semantics, scope, and interaction with the newest-first ordering; `course_id` is only obliquely implied by "in a course."

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?

Names the resource (files in a course) and a meaningful scope detail (newest-first ordering), which distinguishes it from generic listing tools. The verb "list" comes from the name rather than the description, and the closing comparison to canvas_list_linked_files blurs the boundary rather than sharpening it.

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

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

The fallback sentence implies a condition (role-based visibility determines which source is used), which is useful context, but it never states when an agent should choose this tool over canvas_list_linked_files — it only says the two behave similarly. Selection guidance is implied, not explicit.

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

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

Annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds useful behavior beyond annotations by listing the many sources it scans and by naming the fields it returns, though it does not warn about scanning cost or latency.

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

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

The description is front-loaded with the core action and scanning scope, then gives the student distinction and output handoff. The enumeration of scanned sources is long but each item directly supports correct tool selection.

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 scanning tool with no output schema, the description helpfully names the return fields and explains the handoff to canvas_read_file. It is complete enough to call correctly, with only the max_pages parameter left to the schema.

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

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

Only course_id is required, but the description never explains it beyond the phrase 'course's files'. It also does not mention max_pages, and with schema description coverage at 50%, the description leaves a meaningful parameter gap uncompensated.

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

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

The description uses a specific verb and resource: it finds the course's linked files by scanning named Canvas locations. It explicitly distinguishes itself from canvas_list_files by noting that it works for students, so an agent can select it without opening sibling schemas.

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

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

It names the alternative canvas_list_files and the condition that selects this tool: it works for students. It also routes the agent onward by saying to pass file_id to canvas_read_file, which makes the workflow 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context that modules are returned with nested items and reflect the week-by-week course structure. It says nothing about pagination, ordering, or whether item details are truncated.

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

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

A single front-loaded sentence with no filler, and the parenthetical item types earn their place by clarifying return shape. Slightly clipped – it reads as a noun phrase rather than a complete statement of action.

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 one-parameter read tool with annotations and no output schema, the description covers the resource and its nested content but leaves the parameter undocumented and omits ordering/pagination behavior. Adequate but with clear gaps an agent would hit in practice.

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

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

There is one parameter, course_id, at 0% schema description coverage, so the schema adds nothing. The description implies course scoping via 'course modules' but never mentions course_id, its expected format (numeric vs. string ID), or where to obtain it, so it only partially compensates.

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

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

The description names the specific resource (course modules) and clarifies that each module carries its items (pages, files, assignments, links), which distinguishes it somewhat from flat sibling listers like canvas_list_pages or canvas_list_files. However, it never states the verb 'list' or explicitly contrasts itself with canvas_course_snapshot, which likely overlaps in returning course structure.

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 guidance, no prerequisites, and no named alternative. With 20 siblings including canvas_list_pages, canvas_list_files, and canvas_course_snapshot, the agent gets no help deciding whether modules or a snapshot is the right call.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered without description text. The description adds that results are lightweight (title plus slug rather than full page bodies), which usefully signals why you might choose this over other surface area, but says nothing about ordering, pagination, or emptiness handling.

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

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

A single economical fragment with the resource front-loaded and the useful downstream pointer kept short. It earns its place, though it is terse enough that it shades into under-specification rather than pure efficiency.

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

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

For a simple read-only list tool with annotations carrying the safety profile and no output schema, the description covers the core identity and return shape adequately. It falls short on the unexplained `search` filter and on pagination/ordering behavior, both of which an agent needs before invoking it against a large course.

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 neither of the two parameters is explained. The purpose of `search` is never mentioned at all, and it is not obvious from the name whether it matches title, body, or slug. For a low-coverage schema the description should compensate, and here it does not.

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?

Combined with the title 'List pages', the fragment identifies the resource (wiki pages) and its scope (within a course), and also names the exact payload each entry carries (title + url slug). It is distinguishable from siblings like canvas_list_files or canvas_list_modules, though the verb is only implied by the title rather than stated in the description.

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 reference to canvas_get_page implies a two-step pattern (list to get slugs, then fetch a page), which is real but implicit guidance. There is no statement of when to use this versus a direct canvas_get_page call when the slug is already known, and no mention of course_id prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value by disclosing that results include submission status and that the window defaults to the next 14 days. It does not discuss pagination, item ordering, or volume across many courses, which matters for an open-world aggregate query.

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

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

Two compact sentences with zero filler, and the resource scope is front-loaded before the default-window detail. The first sentence is a compressed noun phrase rather than a complete clause, which costs a touch of readability, but nothing is 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?

With no output schema, the description usefully enumerates the item types returned and notes that submission status is included, which is what an agent needs to decide whether this answers a 'what's due' question. Minor gaps remain around result ordering and behavior when course_id is omitted, but the core 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 100%, so each parameter is already documented, including the ISO date defaults and the single-course filter. The description's mention of the default window essentially duplicates the schema's default values, adding no new semantics. Baseline 3 is appropriate when the schema carries this much of the burden.

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 aggregate resource: dated items across courses — assignments, quizzes, discussions, calendar events — plus submission status. That distinguishes it from the narrower siblings like canvas_list_assignments and canvas_list_calendar_events, though it never names those siblings explicitly. The phrasing 'Everything with a date in a window across courses' is slightly telegraphic but unambiguous.

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

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

The default window ('today through 14 days ahead') gives useful context for when the tool applies out of the box. However, it never says when to prefer this aggregated planner view over canvas_list_assignments or canvas_list_calendar_events, which is the main routing decision an agent faces among these siblings.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the bar is lower, yet the description still adds real behavioral context: the download happens server-side, output is rendered as text per format, and truncation is self-reported with a suggested next range. It does not mention permission requirements or failure modes for unsupported binaries, keeping it at 4.

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

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

Three sentences, zero filler: capability and return formats first, input alternatives second, paging/truncation contract last. The parenthetical concrete examples (URL, "3,8-10") are load-bearing rather than decorative.

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

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

With no output schema, the description correctly takes on the return-value burden by describing per-format text extraction and truncation signaling. It is nearly complete for a read tool; only unsupported-file behavior and any size/permission constraints 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?

At 60% schema coverage the description compensates well: it defines the file_id-vs-url alternative, shows a literal URL shape with verifier/wrap query params that the schema does not, and illustrates the `pages` range syntax beyond the schema's "1-5" example. `max_chars` and `course_id` are left to the schema, and `file_id` carries no description in either place.

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

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

Specific verb ('Download ... server-side and return its text') plus resource (course file), with the output shape broken down per format (PDF per page, PPTX per slide with speaker notes, DOCX per section, plain text, ZIP listing). This clearly separates it from canvas_list_files, which only enumerates files.

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

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

Gives concrete selection guidance between the two identifying inputs ('Give file_id, or url = any Canvas file link') and tells the agent to use `pages` for long documents. It stops short of naming when to prefer a sibling (e.g., canvas_get_page for wiki pages) or when this tool is not applicable, so it is clear context without explicit 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?

Annotations already declare readOnlyHint and destructiveHint=false, and the description is consistent with that by noting 'read-only GETs to Canvas.' Beyond annotations it discloses the genuinely important trait: the call blocks up to wait_s and then continues in the background, with a named recovery path. That async/partial-completion behavior is the main thing an agent could get wrong and it is stated plainly.

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

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

Two sentences, front-loaded with the action and scope, followed by the timeout/background caveat and the escape hatch. No filler, and the most failure-prone detail (background continuation) is placed before the alternative tools.

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

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

No output schema exists, and the description does state the return ('the change events it produced'), which covers the main gap for a read tool with safe annotations. What remains thin is the shape and volume of those events and whether archived/inactive courses are silently skipped — minor for this tool class.

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 50%: wait_s is documented in the schema (default 25, max 90) and the description reinforces its semantics via the background-continuation rule. course_id is undocumented in the schema, but the description compensates by implying it is optional and must reference an 'active course,' with omission meaning all active courses. Not exhaustive (no format guidance for the id), but additive.

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?

Names a specific action and resource (take a snapshot), states scope explicitly (one course or all active courses), and states the return (change events produced). An agent can distinguish this from canvas_snapshot_status or canvas_changes_since purely from the wording, since those are named as follow-ups rather than duplicates.

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 trigger is clear enough: use this to run a snapshot immediately, and if the run exceeds wait_s, poll with canvas_snapshot_status / canvas_changes_since. No exclusions are given (e.g., when to prefer canvas_course_snapshot or when not to run this at all), so it stops short of a full when/when-not rubric.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description's added value is disclosing what the response surfaces (403 errors, next run time, DB size), but it says nothing about freshness, cost of the call, or whether errors are summarized versus listed per item.

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

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

A single front-loaded sentence identifying the subject, followed by a compact list of reported fields — no filler or repetition. The list is dense but each item earns its place by telling the agent what data comes back.

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

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

There is no output schema, so the description carries the burden of describing the return value, and it does so concretely (per-course role, last run, duration, item counts, errors, next run, DB size). For a zero-param read-only status tool that is nearly complete; only the relationship to the run/snapshot siblings is 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the baseline rule this lands at 4. The schema is an empty object, consistent with the description's implication that the call is scope-free.

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 resource and scope: 'Health of the snapshot job', with a concrete enumeration of what is reported (per-course last run, duration, counts, errors, next run, DB size). It is clearly not canvas_run_snapshot or canvas_course_snapshot, though it never names those siblings to make the distinction explicit.

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 by the word 'status' — an agent can infer this is for checking/monitoring rather than triggering a snapshot. There is no explicit when-to-use, no mention of the natural pairing with canvas_run_snapshot, and no stated preconditions or 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?

The annotations already declare readOnlyHint, openWorldHint and destructiveHint, so safety is covered. The description adds real value beyond them by specifying the aggregated content categories and the lookback framing of the query. It does not discuss volume, pagination, or what happens when the window yields nothing, which is a minor omission for an aggregation tool.

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

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

Two short sentences, zero filler. The scope and activity types come first and the usage recommendation closes it out, so the agent gets the essential information immediately.

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

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

For a single-optional-parameter read tool with annotations and a fully documented schema, the definition is nearly complete: it says what is aggregated and over what default window. The absence of an output schema leaves the response shape implicit, which 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 100% and the single parameter is fully documented in the schema, including the 26-hour default. The description confirms the temporal semantics ('since a timestamp') but adds no format or edge-case guidance beyond what the schema already states, so the baseline 3 applies.

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

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

The description names the resource clearly: activity across all active courses, with explicit enumeration of the five activity types (announcements, assignments, discussions, grades, messages). The 'across all active courses' scope implicitly differentiates it from per-course siblings like canvas_changes_since and canvas_list_announcements, though no sibling is named directly.

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

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

'Best tool for a daily check' gives a concrete usage context, and 'since a timestamp' frames it as an incremental digest. It stops short of stating exclusions or pointing to alternatives (e.g. canvas_changes_since for a single course), so the agent must infer when not to use it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds the useful fact that the result is scoped to the caller's token, but says nothing about failure behavior (e.g., what an invalid token yields) or what the returned profile contains.

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

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

Two sentences, no filler, and the core behavior ('return the Canvas profile') is front-loaded ahead of the usage hint. Nothing is 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 no-argument, read-only identity probe with no output schema, the definition covers what it does and when to reach for it. A brief note on the shape of the returned profile (id, name, email) or on auth-failure behavior would close the remaining gap.

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

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

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies.

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

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

States a specific verb+resource: returns the Canvas profile associated with the current token. No sibling tool overlaps with an identity check, so there is no ambiguity to disambiguate; the scope ('the token belongs to') is precisely stated.

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

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

'Use to verify the connection works' gives a clear positive trigger (credential/connectivity smoke test). It stops short of naming when not to use it or pointing to sibling tools for anything richer, but for a zero-argument diagnostic the guidance is adequate.

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