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=true and openWorldHint=true, so the safety profile is covered. The description adds the date-format constraint and a usage example, but says nothing about return contents, whether results include both event types merged or separated, or default behavior when optional dates are omitted.

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 statement followed by the format guidance. The worked example earns its place as a disambiguator, though the format advice partially duplicates the schema.

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

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

For a simple two-optional-parameter read tool with no output schema, the description plus annotations cover enough to call it correctly. The main residual gap is the unspecified default range when no dates are supplied.

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 parameters already carry the YYYY-MM-DD format, so the description's repetition of that format adds little. It does not clarify whether the range is inclusive or whether omitting dates returns everything.

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 the resources clearly (calendar events plus assignment due dates) and is distinguishable from most siblings. However, it never contrasts itself with close siblings like get_upcoming_due_dates or export_due_dates_calendar, leaving overlap ambiguous.

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

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

The example question ('What is on my Canvas calendar between...') gives implied usage context and shows how to constrain the range. But there is no explicit when-to-use versus get_upcoming_due_dates / get_todo, and no guidance on what happens if the dates are omitted.

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=true and openWorldHint=true, so the safety profile is covered. The description adds that results include unread counts, a useful output trait. It omits ordering, pagination/truncation, and whether announcements or closed topics are included, which matters for interpreting 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?

Two short sentences with the core purpose front-loaded, followed by a clarifying example. Slight redundancy between the parameter sentence and the schema, and the example uses 'open' in a way the tool doesn't literally support, but nothing is bloated.

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 no output schema, the description covers what it returns (topics plus unread counts) and how to supply the argument. Only result shape details like pagination or ordering are missing, which is a minor gap.

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

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

Schema coverage is 100% and the single parameter is fully documented, including the pointer to get_my_courses for resolving names. The description largely restates the schema ('course_id as the Canvas course ID or as the course name') without adding format or edge-case detail, 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?

States a concrete resource and scope: 'Discussion topics for one Canvas course, with unread counts.' An agent immediately knows this returns discussion data for a single course. It doesn't name a sibling it differs from (e.g. get_announcements), but no sibling plausibly overlaps so the differentiation cost is low.

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 rather than stated as a rule. There is no when-not guidance and no mention of how this relates to get_announcements, which in Canvas is closely related content. The example does anchor the intended invocation reasonably well.

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 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.