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

With annotations declaring readOnlyHint=false, openWorldHint=true, and destructiveHint=false, the description adds substantial context beyond those annotations. It discloses the write-like behavior of saving a file when path is provided, the alternate return of raw calendar text when path is omitted, default exclusion of submitted work, and included event metadata such as course name, points, status, Canvas link, and a day-before reminder.

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 and output modes, then flows into parameters and an example. It is appropriately sized for a tool with five optional parameters and two output paths, though it repeats some defaults already present in the schema, which slightly reduces conciseness.

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

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

There is no output schema, but the description fully explains both return paths: a saved .ics file when path is supplied, or calendar text returned when path is omitted. It also describes event contents and default filtering, leaving no major ambiguity for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters thoroughly. The description adds some extra semantic value, notably that course_id can be either a Canvas course ID or a course name, and reinforces the default filtering and lookahead behavior. The remaining parameter details largely restate the schema, so this is a strong 4 rather than a 5.

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

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

The description states a specific verb and artifact: 'Build an iCalendar (.ics) file of Canvas due dates and calendar events.' It also implicitly distinguishes the tool from read-only sibling tools such as get_upcoming_due_dates and get_calendar_events by producing an exportable calendar file that opens in Google Calendar, Apple Calendar, and Outlook.

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 key usage modes: provide a folder in path to save a file, or omit path to receive calendar text. It also gives defaults for filtering submitted work, the 30-day lookahead, and course filtering, with a concrete example. It does not explicitly name alternatives or when not to use this tool, so it falls short of a 5.

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

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

The annotations already establish read-only and open-world behavior. The description adds useful behavioral context: default page size, pagination behavior, and that course identifiers may be either Canvas IDs or names, with a pointer to get_my_courses for discovery.

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 scope and then covers pagination, parameters, and an example in a compact set of sentences. There is no redundant or 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 simple read-only announcement listing tool with three optional parameters and no output schema, the description covers scope, pagination, defaults, and identifier formats. It does not describe the shape of returned announcement data, but that is a minor omission given the tool's simplicity.

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%, so page and limit are already documented. The description adds meaningful semantics for omitting course_ids, the default of 20 announcements, and cross-tool guidance for obtaining valid course IDs and names.

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

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

The description clearly states the resource (Canvas announcements) and scope (specified courses or all active courses). It is specific enough for an agent to identify the operation, though it does not explicitly differentiate the tool from sibling retrieval tools like get_discussions.

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

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

It explains when to pass course_ids versus omitting them to retrieve announcements across all active courses. It also describes how limit and page affect results and gives a natural-language example, but it does not name alternatives or when-not-to-use 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: the shape of the returned data (name, type, size, link) and the explicit limitation that it does not download or open files. It omits whether files can belong to modules/pages or how inaccessible files appear, 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-loaded with the core action, followed by parameter guidance and a single illustrative example. Each sentence earns its place; the only minor redundancy is restating the ID-or-name flexibility already visible in the schema types.

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 read tool with a fully documented schema, the description covers purpose, input forms, output fields, and a key negative constraint. Absent an output schema, it does list the returned fields, so nothing critical is missing; additional detail on empty results or permissions would push it higher.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by clarifying that both course_id and assignment accept either a numeric ID or a human-readable name, reinforcing the dual type in the schema. The worked example ('Lab 4 assignment in Networking 1') anchors the format usefully, though it does not mention failure behavior for ambiguous names.

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 files linked in one Canvas assignment's instructions', and immediately scopes it with examples like handout/rubric. An agent can distinguish this from get_assignments (assignment metadata) and get_course_content (course-level materials) 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 description gives a concrete usage scenario via the example question and explicitly bounds the tool's scope with 'It does not download or open the files', which pre-empts the most likely mis-invocation. It does not name a sibling alternative (e.g., 'for files at the course level, use get_course_content'), 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?

The annotations already establish read-only and open-world behavior. The description adds useful behavioral context by enumerating the submission statuses returned and explaining that results can be filtered by bucket.

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

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

The description is front-loaded and compact: it states the scope, return fields, filter behavior, and a concrete example without unnecessary 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?

With no output schema, the description appropriately identifies the returned assignment data and status values. The main remaining gap is that it does not explain routing among similar assignment-related tools.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including course name/ID and bucket filtering. The description mostly repeats those details rather than adding new constraints or format semantics.

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

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

The description clearly states it returns assignments for one Canvas course and lists the key returned fields: due dates, points, and submission status. It does not explicitly distinguish itself from overlapping siblings such as get_missing_assignments or get_upcoming_due_dates.

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

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

It gives context for per-course assignment lookup and shows how to filter with bucket, including an example question about overdue assignments. However, it does not state when to use this instead of narrowly scoped siblings like get_missing_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 and openWorldHint, so the safety profile is covered and the bar is lower. The description adds the default page size of 20 and the pagination stepping model, which is useful. It omits whether results span all enrolled courses, how events are ordered, and any timezone handling — meaningful gaps for a calendar 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?

Three tight sentences: what it returns, how to scope it, how to page it, then an example. The most important scoping information is front-loaded. The example sentence is slightly redundant with the prior sentence but earns its place by grounding intent.

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, four-parameter list tool with full schema coverage and no output schema, the description covers scope, format, and pagination adequately. The remaining shortfall is that it never describes the shape of returned events (title, course, due time), which would help an agent decide whether this answers the user's question.

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 every parameter is already documented in the schema. The description repeats the YYYY-MM-DD format and the limit/page defaults without adding semantics such as whether the date range is inclusive or what happens when start_date is omitted. Baseline 3 applies when the schema does the heavy lifting.

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

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

The opening sentence names a specific resource — Canvas calendar events plus assignment due dates — with a clear list verb. It is distinguishable from siblings like get_assignments or get_upcoming_due_dates, though it never explicitly contrasts itself with export_due_dates_calendar or get_upcoming_due_dates.

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

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

The concrete example question ('What is on my Canvas calendar between 2026-10-01 and 2026-10-31?') anchors when this tool applies, and the pagination sentence explains the long-list case. It stops short of stating exclusions — nothing says which sibling to use instead when you want due dates only or an exportable calendar.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that: no indication of pagination, ordering, nesting depth of module items, or whether item content is included or requires follow-up calls. Nothing is stated that the annotations and schema don't already imply.

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 with the resource stated first, followed by the parameter hint and a realistic example. The example earns its place by showing how a user utterance maps to the call; 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?

There is no output schema, so the description carries the burden of explaining what comes back, and 'modules and module items' is thin — it doesn't say what item types appear (assignments, pages, files, quizzes, subheaders) or that results are nested. For a single-parameter read tool this is adequate but leaves an agent guessing about return shape.

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

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

Schema coverage is 100% and the course_id description already explains the ID-or-name duality and points to get_my_courses for lookup values. The description restates the same ID-or-name flexibility without adding format examples, disambiguation rules, or failure behavior, so it matches the baseline 3 for a fully documented single parameter.

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

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

The first sentence names the exact resource returned — modules and module items — scoped to a single Canvas course, which separates it from siblings like get_my_courses (course list) and get_assignments (course work). It lacks an explicit verb such as 'Retrieve' or 'List', so the agent must infer the operation from the resource noun, but the intent 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 natural-language example ('Show me the Week 3 module in my Canvas Networking course') gives a concrete usage cue, but there is no statement of when to prefer this tool over siblings, no exclusions, and no prerequisites. Guidance is implied by example rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context: it explains what each module exposes (state) and what each item exposes (requirement type plus completion), which is meaningful disclosure beyond the annotations.

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

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

The return-value explanation is front-loaded and the parameter notes and example follow in a logical order. It is a bit dense in the opening sentence, but every sentence carries information the agent can use.

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 returns, and it does so adequately by naming module states and item requirement/completion fields. With only two parameters and full schema coverage, little else is missing; a note on ordering or whether items nest under modules would make it complete.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema. The description's parameter guidance ('Pass course_id as the Canvas course ID or as the course name', 'Set only_open to true to hide completed modules') essentially restates what the schema already says, adding no new syntax or format detail. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Your progress through the modules of one Canvas course') and enumerates the returned state (locked/unlocked/started/completed) and per-item requirements. It is clearly distinct from siblings like get_assignments or get_course_content, though it never explicitly names 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?

Usage is implied by 'so you can see what to study next' and the sample question, which gives the agent a sense of the use case. However, it never states when to prefer this over get_todo, get_missing_assignments, or get_course_content, which cover overlapping 'what's left to do' territory.

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 cover read-only and open-world behavior, and the description adds genuinely new context: some emails are hidden from students, so people may appear without one. That is a real data-shape caveat not present in annotations or 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?

Content is front-loaded with the resource and return shape, then filtering, then the email caveat, then an example. Every sentence is useful, though the example is slightly redundant with the earlier 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?

With no output schema, the description supplies the return shape (role, email) and the null-email edge case, and it explains how to obtain a valid course_id. Nothing needed 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 100%, so both parameters are already documented, including the enum and its 'all' default. The description restates that role can be teacher, ta, or omitted for both, adding little beyond the schema; the name-vs-ID hint also duplicates the schema text.

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

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

The opening sentence names the exact resource (teachers and TAs of one Canvas course) and what is returned (role and email). It is clearly distinct from sibling tools like get_my_courses, which is only referenced as an ID source.

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 tells the agent how to supply course_id (ID or course name) and explicitly points to get_my_courses for the list of IDs and names, plus a concrete example question. It lacks a when-not-to-use / alternative-tool exclusion, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful behavior: unread counts are returned and lists default to 20 topics per page with paging. It says nothing about ordering, whether announcements are included, or what happens on invalid course names.

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

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

Three short sentences, front-loaded with the resource and scope, followed by parameter guidance and a concrete example. No filler, though the example sentence is somewhat redundant with the earlier course_id instruction.

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 listing tool with 100% schema coverage and no output schema, the description covers scope, key parameters, defaults, and example usage. The main gap is return-shape hints beyond unread counts, which is a minor omission given the annotations.

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

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

Schema coverage is 100%, so course_id, limit, and page are already fully documented. The description largely restates the schema (course ID or name, default page size, paging), adding no new format or edge-case detail, so it sits at the baseline.

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

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

States a specific resource (discussion topics) scoped to one Canvas course, plus an extra attribute (unread counts). This distinguishes it from get_announcements and get_course_content without needing the schema, though it never uses an explicit verb like 'list' or 'fetch'.

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

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

Gives clear context for when to use it and how, including a worked example question and instructions to page through long lists. It lacks explicit exclusions (e.g., 'use X for announcements or replies'), so it stops short of full when-not 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?

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing the actual behavior per file type: text-based formats return content, while PDF, Word, slide deck and image files return only name, type and size because text is not extracted. It also states the 5 MB download ceiling, which prevents failed calls an agent could not otherwise predict.

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

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

Front-loaded with purpose, then type-handling, then limits, then an example — every sentence carries operational information. The trailing example sentence is the only mildly expendable element and it reinforces the ID syntax rather than repeating it.

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 carries the burden of explaining returns and does so for both the success case (text) and the unsupported-type case (metadata plus note). Size limits and ID provenance are both covered, leaving no significant gap for a single-parameter read tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by giving the concrete form of the identifier ('/files/501') and naming the sibling tools that produce such IDs. This reduces the risk of passing a course ID or name instead of a file 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 ('Read one file from Canvas by its file ID') and immediately scopes it to a single file, which distinguishes it from the listing tools in the sibling set. An agent knows exactly what it gets back 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 points to get_assignment_files and get_course_content as the way to discover a file_id, which is the main prerequisite for calling this tool. It gives clear context for use but stops short of stating when not to use it (e.g., preferring a listing tool when the target file is unknown).

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

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

Beyond the readOnlyHint annotation, it makes the non-obvious guarantee that it 'never marks anything as read' — precisely the side effect an agent would worry about with an inbox tool. It also discloses the default unread filtering and the shape of returned entries, which 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 what the tool returns, then defaults, then pagination, then the safety note, then an example — each sentence carries distinct information with no padding.

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

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

For a simple three-parameter read tool with no output schema, the description covers return contents, ordering, default filtering, pagination, and side-effect guarantees. Nothing an agent needs in order 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 100%, so all three parameters are already documented with defaults and bounds. The description restates the defaults (unread_only true, 20 per page) and frames limit/page as a way to 'step through long lists', adding intent but no new syntax or edge-case detail; 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 specific resource ('Your Canvas inbox'), its ordering ('newest first'), and exactly what each entry contains (subject, participants, last-message time, preview). No sibling tool covers inbox conversations, so ambiguity is effectively zero.

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

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

It states the default filter (unread only) and how to change it, plus how to paginate, and closes with a concrete user question ('Did any instructor message me in Canvas?') that triggers the tool. It stops short of naming when a different sibling (e.g. get_announcements) would be the better choice, but no sibling overlaps this resource.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds the meaningful behavioral detail that only unsubmitted past-due items are returned, plus the returned fields (course, due day). It omits edge cases like items due today or late-but-submitted work.

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: the scope declaration first, then a concrete user-phrasing example. Nothing is wasted and the key filter 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 no parameters and no output schema, the description carries the burden well by naming the returned fields (course and due day). Minor gaps remain around timezone/cutoff semantics for 'past-due' and whether late submissions are excluded, but an agent can call this correctly as-is.

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; baseline applies. No misleading parameter implications are present.

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 with a precise filter: 'past-due Canvas assignments you have not submitted'. The 'past-due' + 'not submitted' scope cleanly separates it from get_upcoming_due_dates, get_todo and get_assignments without needing to name them.

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

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

The example query "What am I missing in Canvas?" gives an unambiguous trigger condition for an agent routing user intent. It stops short of explicitly naming the sibling tools to avoid (get_upcoming_due_dates, get_todo), so it is not 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description does add one real behavioral fact beyond that — only *active* courses are returned, implying concluded/inactive courses are excluded — plus the fact that IDs are exposed for reuse. It says nothing about authentication requirements or whether the list is paginated, so it clears the annotation-lowered bar without being rich.

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

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

Three short sentences, front-loaded with the verb and resource, then the workflow hint, then an example. The example is mildly redundant with the already-explicit purpose, but it costs little and disambiguates 'this term' phrasing.

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

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

For a no-parameter read tool with no output schema, the description covers what an agent needs: what comes back (courses plus their IDs), which courses count ('active'), and what to do with the result. Only the detailed shape of each returned course entry is unspecified, which is a minor gap given there is no output schema to lean 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?

The tool takes zero parameters, which is the baseline-4 case. The description correctly implies no filtering input is needed and that narrowing happens downstream via course ID in sibling tools, which is the only 'parameter-like' semantics that matters here.

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 active Canvas courses with their Canvas course IDs' — which is unmistakable against siblings like get_todo or get_announcements. It doesn't explicitly name a sibling or claim a unique niche, but the 'my courses' discovery role is obvious from the return value it promises.

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 context: this is the entry point, and the returned course ID/name is the handle to feed into the other tools. The sample question anchors the intended use. It stops short of stating exclusions (e.g., 'do not use to get grades or content — call the course-specific tools'), so it's not 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral value by disclosing the data source (Canvas gradebook), the scope restriction to active courses, and the exact payload components (score, points possible, submission status). It does not discuss behavior for courses with no graded assignments, but the gap is minor.

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: what is returned, how to scope it, and a representative query. Zero redundancy and the scope constraint is front-loaded before the optional-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?

With one optional parameter, no output schema, and full schema coverage, the description supplies everything needed: data source, scope semantics, return shape, and a usage example. Nothing an agent needs to select or invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description exceeds that by clarifying that course_id accepts either a Canvas course ID or a course name — a format detail the schema's string|number union does not convey — and by restating that it narrows both the grades and the assignment breakdown.

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 — current grade per active Canvas course plus the assignments behind each grade (score, points possible, submission status). It is clearly distinct from data-oriented siblings like get_todo or get_missing_assignments, though it never explicitly contrasts with get_target_grade, which is the closest conceptual neighbor.

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 example question ("What is my grade in each Canvas course and which assignments make it up?") gives a concrete trigger context, and the course_id sentence explains the narrowing behavior. However, no when-not conditions or named alternatives are offered, so the agent must infer exclusion cases on its own.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral detail — default page size of 20, a 100 cap implied by the schema, and that results include the caller's own attempts and score. It says nothing about authentication, rate limits, or what happens for unpublished quizzes, so it is a moderate rather than rich addition.

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

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

Front-loads what the tool returns, then groups scoping, filtering, and pagination guidance, and closes with a natural-language example query. Dense but every clause carries information; the closing example is slightly decorative but reinforces the trigger phrasing.

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

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

With no output schema and four optional parameters, the description covers returned fields, scope defaults, filtering semantics, and pagination well enough to call the tool correctly. Minor gaps remain around what counts as an 'active course' and behavior when a course name is ambiguous.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds meaning: course_id accepts either a numeric Canvas course ID or a course name, and when=upcoming means 'not yet closed' rather than merely 'in the future'. It also restates the 20-item default in a usable way.

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 (Canvas quizzes and exams) and enumerates exactly what each result carries: open time, due time, close time, time limit, attempts used, and score. That is enough to distinguish it from siblings like get_assignments or get_discussions without opening a schema.

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

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

Gives clear operating contexts: pass course_id to scope to one course (by ID or name) or omit it for all active courses, and use when=upcoming vs past to select unclosed vs closed quizzes. It never names an alternative sibling tool for assignment or grade data, so routing guidance stops short of explicit alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds that this returns instructor comments and score/grade for the user's graded submission, but does not cover edge cases such as missing feedback, ungraded submissions, or permission behavior.

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

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

The description is front-loaded with purpose, then parameter forms, then a natural-language example. It is concise overall, though the parameter guidance substantially duplicates the already-rich schema descriptions.

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

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

For a simple two-parameter read tool with full schema descriptions and readOnly/openWorld annotations, the description gives enough context to call it correctly. It also indicates the return content, which helps since no output schema exists, but it omits edge-case behavior.

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

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

Schema description coverage is 100%, and the schema already documents both course_id and assignment including accepted names/IDs and references to get_my_courses/get_assignments. The description repeats the same accepted forms without adding new parameter semantics 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?

The description clearly states the resource and scope: instructor comments on a graded submission for one Canvas assignment, including score and grade. It implicitly distinguishes this from broader sibling tools like get_my_grades or get_assignments, but does not explicitly name 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?

Usage is implied through the example question and the mention of passing course/assignment identifiers. However, there is no explicit guidance on when to choose this tool over siblings such as get_my_grades or get_assignments, nor any 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one useful behavioral detail — HTML is removed from the output — but says nothing about what happens when a course has no syllabus or about rate limits, leaving a modest gap.

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 plus an example, with the core action front-loaded. The quoted example is slightly redundant with the sentence before it, but nothing is padded or buried.

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 full schema coverage and no output schema, the description covers the essential contract and the HTML-stripping behavior. A note on empty-syllabus 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?

Schema description coverage is 100%, so the single parameter's dual ID/name semantics are already fully documented in the schema. The description merely restates that course_id accepts an ID or a name, adding no format or disambiguation 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?

The description states a specific verb and resource: returns the syllabus text for one Canvas course, with HTML stripped. That is more precise than a tautology, but it never distinguishes itself from the potentially overlapping sibling get_course_content, so an agent must infer the boundary.

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 example question ("What does the Canvas syllabus say about grading in Scripting?") implies the intended use case, but there is no explicit when-to-use vs when-not guidance and no named alternative (e.g., get_course_content) for broader course material.

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 readOnlyHint and openWorldHint already declared, the description adds useful behavioral context: it explains that the tool computes from graded points unless current_percent is supplied from Canvas. It does not describe failure modes or the exact response shape, but it meaningfully supplements the annotations.

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

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

The description is front-loaded with the purpose and appropriately sized for a simple calculator. It includes a helpful example, though some parameter explanation duplicates the schema and could be tighter.

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, three-parameter calculator with no output schema, the description covers the core inputs and calculation concept well. It could be more complete by noting what the result includes or how impossible/edge targets are handled, but it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description repeats course_id, target_percent, and current_percent semantics, adding only slight nuance about using Canvas-reported percent instead of computing from graded points.

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 calculation: determining the score needed on remaining Canvas work to reach a target percent in one course. This is clearly distinct from sibling tools like get_my_grades because it computes a required future score rather than reporting current grades.

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 a clear usage scenario and example question, so an agent knows when this calculator is appropriate. It does not explicitly state when not to use it versus get_my_grades or other grade-related siblings, 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the meaningful constraint that only items Canvas marks as needing attention are returned, but says nothing about ordering, pagination, or whether completed items linger.

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 declarative sentence establishing what is returned, followed by a short example utterance. Front-loaded, no filler, and every clause earns its place.

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

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

For a zero-parameter read-only tool with no output schema, the description gives enough to call it correctly and anticipate content (assignments and discussions with due dates). A brief note on entry contents or ordering would make it fully complete.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description is needed to explain inputs, and it correctly presents this as a parameterless call.

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

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

States a specific verb (get) and resource (Canvas to-do list) and defines scope: assignments and discussions that Canvas flags as still needing attention, with due dates. That scope implicitly separates it from get_assignments and get_upcoming_due_dates, 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?

The example question ("What does Canvas say I still need to do?") implies when to reach for this tool, but there is no explicit guidance on when to choose it over get_missing_assignments, get_upcoming_due_dates, or get_assignments. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds ordering (soonest first), coverage scope (every course), and the default behavior when the optional window is omitted, which is real context beyond the annotations. It does not discuss pagination or result caps.

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

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

Three short sentences, front-loaded with what the tool returns, then the parameter guidance and an example. Minor redundancy: the 'leave it out and everything is included' point duplicates the schema wording almost verbatim.

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-only listing tool with no output schema, the description covers scope, ordering, and default behavior well enough to call correctly. The one remaining gap is the shape of returned items (what fields accompany each due date), which an output schema would otherwise have carried.

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

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

Schema description coverage is 100%, so the single parameter's meaning and omission semantics are already fully documented by the schema. The description restates this and adds only a concrete example value (3), so baseline 3 is appropriate.

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

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

States a specific verb and resource: upcoming assignments and events across every Canvas course, returned soonest first. That aggregation-across-all-courses scope helps separate it from per-course siblings like get_assignments and get_calendar_events, but those siblings are never named, so differentiation is implicit.

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 two usage modes clearly: pass days_ahead to limit the window, omit it to get everything Canvas returns, and gives a worked example query. It stops short of saying when to prefer this over get_todo or get_calendar_events, so the alternative selection is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the description's job is added context, which it delivers: it discloses that results are split into three sections, that each section defaults to 20 items, and that long lists are paginated. It does not mention the 60-day cap on since_days or anything about result ordering, but the operational shape is well conveyed.

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 aggregate purpose, then parameter behavior, then an example — a sensible order. A few phrases duplicate schema defaults (20 items, page) but they aid scanning rather than bloating the text; total length is appropriate for a four-parameter tool.

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

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

With no output schema, the description must convey what comes back, and it does by naming the three result sections and their pagination. An agent can call it correctly and interpret the response. Minor gap: it doesn't say whether limit applies per section or overall, nor how empty sections appear.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns an extra point by clarifying that course_id accepts either a numeric Canvas course ID or a course name — information the schema does not provide. It also restates the effective defaults (7 days, 20 items) and the paging model, adding light but real meaning.

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

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

The description names a specific aggregate resource — a single catch-up across Canvas courses — and enumerates its three sections (announcements, graded assignments, unread discussions). This clearly separates it from narrower siblings like get_announcements, get_discussions, and get_todo without the agent needing to open any schema.

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

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

It gives concrete invocation contexts: use it for a general catch-up, narrow with course_id to check one course, widen with since_days, and page with limit/page. It even supplies a natural-language example query. It stops short of explicit exclusions (e.g. 'for only announcements, use get_announcements'), so it is clear context rather than full routing guidance.

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