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

Annotations declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the write/network profile is already covered. The description usefully adds the validation rules (only configured Canvas host URLs accepted; destination confined to CANVAS_OUTPUT_DIR), but never explains the destructive aspect or mentions the `overwrite` parameter at all, leaving the reason for the destructive hint unexplained.

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

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

Two sentences, purpose front-loaded, with constraints in tight parentheticals. The density is slightly heavy but nearly every clause carries necessary constraint information, so there is little waste.

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 absence of return-value information is acceptable, and the security constraints are covered. But for a file-writing tool flagged destructive, the missing explanation of `overwrite` semantics and of what gets destroyed leaves a real gap for correct invocation.

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

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

Schema coverage is 67%, and the description mirrors the schema for `url` and `destinationPath`, adding the env-var name and default directory plus path-resolution behavior. However `overwrite` is undocumented in both the schema and the description, so the description does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Download a Canvas file to disk') and immediately differentiates itself from the sibling canvas_list_course_files by naming it as the source of the `url`. An agent can tell this is the write-side counterpart to the listing tool without opening either schema.

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

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

Gives clear usage context: the `url` must come from canvas_list_course_files, and `destinationPath` must live in the download directory. It does not explicitly state when not to use it (e.g. alternatives for bulk download or non-Canvas URLs), so it falls just short of full when/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?

Annotations already cover the safety profile (readOnlyHint, openWorldHint), but the description adds a genuinely useful side-effect disclosure: it does not mark the conversation as read, which is non-obvious for Canvas conversations that are normally flagged read on view. It stops short of describing return shape or pagination.

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 tight sentences with the core action front-loaded and the read-only caveat immediately after. There is no filler or restatement of the tool name.

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 reasonably signals that a full thread of messages comes back, and the read-only note covers side effects. But it leaves the identity of the required 'id' unresolved and says nothing about pagination or large-thread behavior, gaps an agent must resolve by guessing.

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 only 50%: the 'view' enum is exhaustively documented in the schema, but the required 'id' parameter carries no description anywhere, and the description does not say whether it is a conversation ID, user ID, or thread ID. That omission is exactly where the description should have compensated.

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

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

States a specific verb and resource ('Get a full Canvas conversation thread with all messages'), which differentiates it from the sibling canvas_list_conversations by implying a single thread rather than a list. It does not name the sibling explicitly, so the differentiation is inferred rather than stated.

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

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

Usage is implied by 'Get a full conversation thread' versus listing conversations, and the 'does not mark as read' note hints at when a non-mutating read is wanted. However, there is no explicit when-to-use statement and no named alternative the way a stronger definition would provide.

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 cover readOnlyHint and openWorldHint, so safety profile is known. The description adds no behavioral context beyond purpose: no auth requirements, rate limits, error behavior for nonexistent/unauthorized courses, or pagination. It could have explained the 'view' trade-off but leaves that entirely to the schema.

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

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

One short sentence with zero filler. Front-loaded verb+resource and immediately enumerates the notable returned sub-resources.

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

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

No output schema exists, and the description names only three returned fields (syllabus, teachers, term) while the tool actually returns a full course payload. Combined with a bare courseId and no usage or behavioral context, the definition is usable but leaves meaningful gaps for an agent to fill from Canvas knowledge.

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

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

Schema coverage is 50%. The 'view' parameter is thoroughly documented in the schema, but courseId has no schema description and no description text compensates—its format (numeric vs string identifier) is unspecified. Baseline 3 since the main documented parameter is well covered.

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 (single Canvas course), and names what it returns (syllabus, teachers, term). Differentiated from canvas_list_courses by 'single', though it does not name that sibling explicitly.

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

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

No when-to-use guidance, no alternatives named, and no mention of prerequisites like enrollment or permissions. The description only states what the tool fetches, leaving the agent to infer that this is for a single course rather than a listing.

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 concrete returned field set and the credential-verification framing, but says nothing about auth requirements, failure modes, or rate limits beyond what annotations provide.

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

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

Two short sentences, zero filler, with the core purpose and the returned fields front-loaded before the usage hint. 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?

With no output schema, the description usefully enumerates the profile fields (id, name, primary_email, login_id, locale, time_zone) so the agent knows what comes back. Combined with the annotation-covered safety profile, this is nearly complete, though it omits any note on error behavior when credentials are invalid.

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 'view' parameter carries an unusually thorough schema description covering compact vs full, dropped avatar fields, and link-field survival. The description adds nothing about parameters, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Get the logged-in user's Canvas profile') and enumerates the fields returned, which makes it easy to distinguish from generic sibling list tools like canvas_list_courses. It stops short of explicitly contrasting itself with any named sibling (e.g., canvas_healthcheck), so it is clear but not sibling-differentiated.

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?

'Useful first call to confirm credentials' implies when to reach for it, giving the agent a real use case. However, there is no statement of when NOT to use it and no named alternative, so usage is only implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description usefully discloses response content (rubric assessment, grader comments), but says nothing about permission requirements, error behavior for a missing/unauthorized submission, or whether an unpublished grade is visible.

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

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

Two short sentences with the core action front-loaded and zero filler. Nothing is padded or restated.

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 must carry return-value information; it names rubric assessment and grader comments but not the broader field set or the shape of the result. Combined with undocumented required params, this is minimally viable rather than 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 two required parameters, courseId and assignmentId, have no schema descriptions and no explanation in the description. The only parameter content in the description repeats the userId default that the schema already states, so it adds no meaning over structured data at 50% coverage.

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

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

States a specific verb and resource ('Get a single submission') and adds that the payload carries rubric assessment and grader comments. 'Single' implicitly contrasts with the list_submissions siblings, but it never names them, so the differentiation is left to inference.

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

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

No when-to-use guidance, no prerequisites (e.g., enrollment/permission requirements), and no routing to alternatives such as canvas_list_recent_submissions or canvas_list_missing_submissions. The only hint is that userId defaults to 'self', which is a parameter detail rather than usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description reinforces the read-only nature ('Read-only; never returns the credential itself') and adds behavioral detail: it resolves the credential, makes one authenticated request, and reports specific diagnostic outputs. This goes beyond the annotations by describing the internal steps and the safety guarantee, which is valuable.

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 efficient and front-loaded: it starts with the core action, then lists the reports, then gives a safety note, and ends with usage guidance. Every sentence adds value with no redundancy. It is well-structured for quick parsing.

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

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

For a simple tool with no parameters and no output schema, the description covers all necessary aspects: what it does, what it reports, when to use it, and a safety guarantee. An agent can invoke it correctly and understand its results without missing information.

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 has zero parameters and the schema is trivially complete (100% coverage). Since there are no parameters, the description does not need to explain parameter semantics. It correctly focuses on behavior and output, which is appropriate for a no-argument tool.

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: it resolves credentials and makes an authenticated request to canvas, reporting diagnostic details. It clearly distinguishes itself from sibling list/get tools by being a healthcheck, and names the exact output categories (source, acceptance, RTT, hint).

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

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

It gives an explicit trigger condition: 'Call this when a real tool fails and you want to know which hop broke.' This is clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives, though none exist among siblings. The guidance is adequate but not exhaustive.

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

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

Annotations cover read-only and open-world behavior. The description adds the 'Defaults to active-only' behavioral note, which is useful context beyond the schema since activeOnly has no description in the schema. However, it doesn't disclose pagination, default ordering, or the relationship between activeOnly's default and the explicit parameter.

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

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

Three compact sentences, front-loaded with the purpose. No filler. Could be improved by grouping the parameter notes more cleanly, but it's efficient.

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

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

No output schema exists, so the description should do more to explain the return shape, pagination, and date formats. With 5 parameters and only 40% schema coverage, the description fills some gaps but leaves startDate/endDate and return structure unexplained. Adequate but incomplete.

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

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

Schema coverage is 40%, with only contextCodes and view documented in the schema. The description emphasizes contextCodes format and the activeOnly default, but startDate and endDate formats are left undocumented in both schema and description. It partially compensates but leaves clear gaps.

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

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

States a specific verb + resource ('List announcements') and adds the multi-course scope. It's clear what the tool does, though it doesn't differentiate from any specific sibling since none of the siblings appear to list announcements.

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

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

No guidance on when to use this tool versus alternatives, no exclusions, and no mention of prerequisites. It only notes that contextCodes is required, which is already in the schema.

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 usefully adds that submissions are inlined and that filtering happens Canvas-side, but says nothing about pagination, ordering, or return size for what could be a large list.

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

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

Two tight sentences, with the core purpose and the inline-submission detail front-loaded. No filler, though the bucket sentence is thin enough that it barely 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?

With no output schema, the description should carry more of the return-value burden; it mentions inlined submissions but omits pagination, ordering, and result size. Adequate for a simple list tool but with clear gaps.

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

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

Schema coverage is 50%: `bucket` has both a description and an enum, while `courseId` is undocumented but self-evident. The description only gestures at the filter ('standard Canvas bucket filter') without explaining the enum values, so it adds little beyond the schema.

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

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

States a specific verb and resource ('List a course's assignments') and adds the notable scope detail that the user's own submission is inlined, which helps distinguish it from canvas_get_submission and canvas_list_missing_submissions. It stops short of explicitly naming a sibling to contrast against.

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

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

There is no guidance on when to choose this over canvas_list_missing_submissions, canvas_get_submission, or the other submission-listing tools. 'Supports the standard Canvas `bucket` filter' hints at a narrowing use case but never says when that filter is appropriate.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and reach are covered. The description adds that results can be either calendar events or assignments depending on scope, which is useful, but it says nothing about pagination, date-range defaults, or whether an empty contextCodes returns everything.

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

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

A single front-loaded sentence with no filler or repetition. It is appropriately terse, though for a five-parameter tool with low schema coverage the brevity leaves real gaps rather than being purely efficient.

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

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

With five optional parameters, 40% schema coverage, and no output schema, the description is too thin. An agent cannot tell how endDate interacts with startDate, what allEvents does when contextCodes is omitted, or what shape the returned list takes.

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 only 40%: startDate and contextCodes are documented, while type (an enum), endDate, and allEvents carry no schema text. The description indirectly covers type ('events or assignments') and contextCodes ('courses/users'), but leaves endDate and allEvents unexplained, so it only partially compensates for the coverage gap.

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

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

The description gives a specific verb and resource ('List Canvas calendar events or assignments') plus the scope ('across selected contexts (courses/users)'). It is clear what the tool does, but it offers no differentiation from close siblings such as canvas_list_upcoming_events, canvas_list_planner_items, or canvas_list_assignments, all of which plausibly return overlapping data.

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

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

There is no statement of when to use this tool versus the several sibling listers that also surface assignments or events. The phrase 'across selected contexts' hints that the caller must supply context, but no conditions, prerequisites, or exclusions are given.

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 no behavioral context of its own: no pagination behavior, no default view, no note that it returns a conversation collection while canvas_get_conversation returns one, and no auth or rate-limit hints.

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, front-loaded with the purpose and no filler. Nothing is wasted, though the second sentence could have spent its words on the undocumented `view` parameter rather than repeating enum values.

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 must carry return-shape information, yet it says nothing about the response format (compact vs full), pagination, or ordering. Combined with the missing sibling differentiation and the ignored `view` parameter, it is under-specified for a list endpoint.

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

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

With 67% schema coverage, the schema already documents `filter` and the complex `view` parameter in detail. The description merely restates the `scope` enum values (already in the schema) and briefly echoes `filter`, while completely omitting `view`, the parameter with the richest 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?

States a clear verb+resource: 'List Canvas inbox conversations.' The plural 'List' plus the resource distinguishes it implicitly from the singular sibling canvas_get_conversation, but it never names that sibling or any other, so the differentiation is left to inference.

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

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

There is no when-to-use guidance, no mention of the sibling canvas_get_conversation for retrieving a single thread, and no indication of when unread/starred/archived/sent scopes matter. The description simply enumerates optional parameters.

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 genuinely useful behavioral context by clarifying that no file content is returned and that the `url` field is the handoff point to the download tool. It stops short of mentioning pagination, rate limits, or auth scope.

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

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

A single front-loaded sentence that leads with what the tool returns and immediately follows with the alternative it is not. Zero wasted words.

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

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

For a simple read-only listing tool with no output schema this is close to adequate, since the return shape is described conceptually. The missing documentation of the two optional filter parameters is the notable gap that keeps it from being complete.

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

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

Schema description coverage is 0% and the description says nothing about the three parameters, leaving searchTerm and contentTypes completely undocumented in both places. The only field mentioned (`url`) is a return value, not an input, so the description does not compensate for the schema gap.

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

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

The description states a specific verb and resource ('List a course's files') and explicitly distinguishes the tool from its closest sibling by noting it returns metadata only versus canvas_download_file. An agent can tell the two apart without opening either schema.

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

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

It names the alternative (canvas_download_file) and the condition that selects it ('metadata only — use canvas_download_file with the `url` field'), giving clear routing guidance. It does not, however, say when to prefer this tool's searchTerm/contentTypes filtering over just listing everything.

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 content detail (grades, total scores, grading period scores, term) but says nothing about pagination, scope limits, or whether inactive/completed courses are excluded — 'active' is asserted without definition.

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

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

A single front-loaded sentence with no filler; the parenthetical enumerates return contents efficiently. Slightly dense but every clause carries information.

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

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

With no output schema, the description usefully previews the returned fields, which is the main thing it owes the agent. It still omits pagination/result-size behavior and the meaning of 'active', leaving a real gap for a list endpoint.

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

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

Only one parameter (observeeId) and the schema description covers it 100%, including the 'omit for self' default. The description adds no parameter-level meaning beyond the schema, 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 specific verb and resource ('List active Canvas courses') and enumerates the payload (course-level grades, total scores, current grading period scores, term). An agent can distinguish it from the singular canvas_get_course, though the description never names that sibling explicitly.

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

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

No when-to-use or when-not-to-use guidance. It doesn't explain the relationship to canvas_get_course (single course), canvas_list_enrollments, or canvas_list_observees, so the agent must infer selection from names alone.

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

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

The parenthetical '(read-only)' merely restates readOnlyHint=true already declared in annotations, earning no credit. Nothing is said about pagination, ordering defaults, or what onlyAnnouncements actually does to the result set, which is the one behavior an agent would most want disclosed here.

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

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

A single front-loaded sentence with zero filler, which is appropriate for the format. It is arguably undersized for a 4-parameter tool rather than wasteful, so the structure itself is sound.

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 annotations covering only safety, the description should explain at least ordering, the announcement filter, and how compact vs. full differ. All four parameters except 'view' are left unexplained, so an agent cannot confidently call this with orderBy or onlyAnnouncements.

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

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

Schema coverage is only 25%: the 'view' enum is documented in the schema (with good detail), but orderBy, onlyAnnouncements, and courseId have no description anywhere. The tool description adds nothing about any parameter, so it fails to compensate for the coverage gap on a tool whose onlyAnnouncements flag materially changes the output.

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

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

States a specific verb and resource ('List discussion topics') plus the scope ('for a course'), so the agent knows exactly what it retrieves. It does not distinguish itself from the nearest siblings (canvas_list_announcements, which overlaps if onlyAnnouncements is set), leaving differentiation to the name alone.

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

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

No when-to-use or when-not-to-use guidance, and no mention of the alternative canvas_list_announcements despite the onlyAnnouncements parameter making the two overlap. Usage must be inferred entirely from the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety and external-data profile. The description adds that only active enrollments are returned and enumerates the grade fields, which is useful context, but it omits pagination, ordering, and scope behavior.

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

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

A single front-loaded sentence that names the resource and the salient return fields with zero padding. It earns its place and is appropriately sized for the tool's complexity.

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-param read tool, the coverage is minimal but workable: annotations carry safety, and the description discloses what is returned. However, it does not document the lone parameter or distinguish its enrollment scope from sibling list tools, leaving real gaps given the crowded sibling set.

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?

One parameter (observeeId) with 0% schema description coverage, and the description never mentions it. The description implies a list scoped to some student, but an agent cannot tell from either source what observeeId means or that it is the observability/parent-proxy identifier.

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

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

States a specific verb (list) and resource (active student enrollments) with extra detail on the returned grade fields. It does not differentiate itself from sibling list tools like canvas_list_observees or canvas_list_courses, leaving the agent to infer the enrollment-vs-observation distinction.

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

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

No when-to-use guidance and no named alternative. The description does not explain that this tool is for enrolled students' grades versus, say, canvas_list_observees or canvas_list_courses, so an agent deciding among the ~18 sibling list tools gets no routing help.

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 safe-read profile is covered structurally. The description adds only the observee/courseIds coupling, saying nothing about pagination, result volume, or what an unsubmitted item looks like. With annotations carrying the safety burden, 3 is appropriate.

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

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

Two short sentences, zero waste, with the core scope front-loaded and the conditional requirement second. Nothing could be removed without losing meaning.

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-only listing tool with full schema coverage and annotations covering safety, the description gives an agent everything needed to call it correctly. The only omission is return shape, which is minor 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 description coverage is 100% and both parameters are already documented in-schema, including the observeeId→courseIds dependency. The description restates that same requirement rather than adding new semantics, 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 specific verb and resource with a sharp scope qualifier: 'List past-due unsubmitted assignments for the user (or a linked observee).' The 'past-due unsubmitted' filter distinguishes it in practice from canvas_list_assignments and canvas_list_recent_submissions, though it never names a sibling explicitly, which keeps it short of a 5.

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

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

Provides a clear conditional prerequisite: 'For an observee, courseIds is required,' which tells the agent exactly when to supply courseIds. It offers no guidance on when to choose this tool over the other submission/assignment listers, and no exclusions, so it stops at 4.

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 genuinely useful behavior fact (empty array for plain student tokens), but says nothing about pagination, result ordering, or the shape of returned student entries.

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, front-loaded with the core action and followed by the highest-value edge case. Nothing is wasted.

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

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

For a read-only listing tool with full schema coverage and no output schema, the description covers purpose, audience, and the notable empty-result case. Pagination or field-set expectations for the returned students would make it fully self-sufficient.

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

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

Schema description coverage is 100% and the single 'view' parameter already documents its compact/full semantics in detail. The description adds no information about the parameter, 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?

Specific verb+resource: 'List students linked to your Canvas observer account.' The 'observer account' qualifier differentiates it from the other canvas_list_* siblings by audience, though it never names an alternative 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?

Clear context for use (observer accounts) plus an implicit exclusion: plain student tokens yield an empty array, so an agent knows this is the wrong tool for a student-authenticated session. No named alternatives, but the condition that selects the tool is 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 safety and network scope are covered. The description adds useful surface area by revealing that the result is a merged feed of four item types, but says nothing about pagination, how startDate/endDate bound the result, or authentication for observee access.

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

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

A single front-loaded sentence with no filler; the parenthetical enumeration of item types is dense but carries real information. It is efficient, though it stops short of any routing or scoping guidance.

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

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

For a five-parameter, no-output-schema tool, the description leaves an agent unable to determine date-range behavior, pagination, or the meaning of the filter enum. It covers the item taxonomy but not the mechanics needed to invoke 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 0% across five parameters, and the description only loosely gestures at observeeId ('a linked observee'). It never explains the filter enum value 'new_activity', the startDate/endDate format or semantics, or what contextCodes restricts. With this coverage gap, the description must compensate and does not.

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

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

The description names a specific verb (List) and resource (planner items) and enumerates exactly what the collection contains: assignments, announcements, planner notes, calendar events. That distinguishes it from siblings like canvas_list_assignments or canvas_list_calendar_events, which cover only one type each, though it never explicitly says it aggregates those siblings.

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

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

The clause 'for the user or a linked observee' hints at the observeeId use case, but there is no statement of when to call this instead of canvas_list_assignments, canvas_list_announcements, or canvas_list_calendar_events. No exclusions, prerequisites, or date-window context are given.

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 two useful behavioral facts — the default 14-day window and that it scopes to 'the calling user' — but says nothing about pagination, ordering, or volume, which matter for a list endpoint.

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

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

Two short sentences with no filler, and the scope constraint (14-day default window) is front-loaded where an agent will see it. It is efficient, though the terseness leaves room that could have been spent on filtering guidance.

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

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

With four parameters, one enum, no output schema, and no mutation, the description is minimally viable but thin: it omits what 'recently graded' means operationally, whether results are ordered or paged, and how the studentId filter interacts with the calling-user default.

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 a high 75% and the schema already spells out the since default (14 days ago), studentId default ('self'), and an unusually detailed view enum. The description merely restates the 14-day default already in the schema and adds nothing about view or studentId semantics, so it sits at the baseline for schema-heavy definitions.

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

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

States a specific verb+resource ('List recently graded submissions') plus the scope qualifiers 'in a course' and a 14-day default window, which differentiates it from generic list tools. However, it never names the closely related siblings it could be confused with (canvas_list_missing_submissions, canvas_get_submission), so differentiation requires inference.

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

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

There is no when-to-use guidance and no alternatives named. An agent cannot tell from the description when to reach for recent submissions versus canvas_list_missing_submissions or canvas_get_submission, nor what the default window implies about coverage of older work.

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 burden is lower. The description adds a useful behavioral constraint - the curated 7-day window - but says nothing about pagination, ordering, or return shape.

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

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

A single front-loaded sentence with zero waste; the scope qualifier is parenthetical and does not bury the core action.

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

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

For a zero-parameter read tool whose annotations already declare safety, the description covers scope and context adequately. Only the lack of any return/pagination note and routing to similar list tools keeps it from a 5.

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 schema is trivially complete (coverage 100%) and there is no parameter meaning the description needs to compensate for. Baseline 4 applies.

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

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

States a specific verb ('List') and resource ('upcoming events') scoped to the calling user, and clarifies the window as Canvas's curated next-7-days view. It does not explicitly distinguish itself from overlapping siblings like canvas_list_calendar_events or canvas_list_planner_items, which is why it falls short of a 5.

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

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

The 'next-7-days view' scope implies when this tool applies, but there is no explicit when-to-use/when-not guidance and no mention of the closely related calendar/planner siblings. Usage must be inferred from the scope statement.

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