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

Annotations already indicate destructiveHint and openWorldHint, but the description adds valuable specifics: the URL host restriction, the required destination directory, and the relative path resolution. These details go beyond annotations and clarify the tool's side effects and constraints.

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 efficient sentences, front-loaded with the core action and immediately followed by constraints. No wasted words; every clause adds necessary 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?

The description covers the main constraints and path resolution, but it omits the behavior of the 'overwrite' parameter (e.g., what happens if the file exists). For a tool with no output schema and a potentially destructive operation, this is a notable gap. Otherwise, it is largely complete.

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

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

Schema coverage is 67% with descriptions for url and destinationPath, both of which are also echoed in the description. The description adds little new semantic value for those two parameters. The 'overwrite' parameter is completely undocumented in both the schema and the description, so the description fails to compensate for that missing parameter. At moderate coverage, this is a reasonable baseline.

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

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

The description clearly states 'Download a Canvas file to disk' with a specific verb and resource. It distinguishes itself from sibling tools (all list/get operations) by being the only download action, and it references canvas_list_course_files as the source, providing immediate differentiation.

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 explicitly states that the url must come from canvas_list_course_files and be on the configured host, and that destinationPath must be inside the download directory. These are concrete usage constraints, and since no alternative download tool exists, this fully guides when to use it.

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

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

The readOnlyHint annotation already marks this as a read-only operation, and the description adds a useful specific behavior: it does not mark the conversation as read. This is a non-obvious side-effect guarantee that goes beyond the annotation and helps an agent avoid assuming a GET request will update read state.

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

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

Two short sentences, front-loaded with the core purpose and then the important read-state behavior. Every phrase earns its place, and the description avoids repeating schema details already present in the view parameter.

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 single-resource tool with no output schema, the description plus the detailed view parameter docs provide enough to call it correctly. The main gap is the lack of explicit id semantics, but the tool name and 'conversation thread' phrasing make the intended usage fairly clear.

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 view parameter is richly documented in the schema, so no additional description is needed there. However, the required id parameter has no schema description, and the tool description only loosely implies it is the conversation ID without stating the expected format or providing explicit confirmation.

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: 'Get a full Canvas conversation thread with all messages.' This makes the tool's purpose immediately distinguishable from sibling list tools like canvas_list_conversations, which enumerate conversations rather than returning a single thread.

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

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

The description implies the tool should be used when a caller needs the complete thread for one conversation, but it never explicitly names canvas_list_conversations as the alternative or states when not to use this tool. The guidance is present only by implication, relying on the sibling tool names for context.

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 readOnlyHint annotation already establishes that this is a safe read operation, and the description aligns with that by saying 'Get'. It adds a bit of context about the returned content but does not disclose error behavior, permissions, or response format beyond what the schema's view parameter already explains.

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. Every word earns its place and the core purpose is immediately visible.

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

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

For a simple read-only tool with one required parameter and readOnlyHint annotation, this is largely complete: the caller knows what to supply and what the response will include. It could mention alternatives or edge cases, but nothing critical is missing for basic 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?

The description adds no direct parameter explanation. The schema thoroughly documents the view parameter, and courseId is self-evident from its name and required status. With 50% schema description coverage, the description does not compensate for courseId, but the parameter is unambiguous enough that the gap is minor.

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'), a specific resource ('a single Canvas course'), and the distinguishing content the response includes: syllabus, teachers, and term. This clearly differentiates it from list-oriented siblings like canvas_list_courses.

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

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

The description implies when to use the tool: when a single course with its syllabus, teachers, and term is needed. However, it does not explicitly state when not to use it or name alternatives such as canvas_list_courses, leaving some routing 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 declare readOnlyHint=true, and the description's 'Get' action is consistent with that. The description adds the diagnostic value of confirming credentials, but it does not add deeper behavioral detail such as auth requirements, rate limits, or error behavior. Given the annotation coverage, a 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 sentences with no filler: the first states the action and result fields, the second gives the practical use case. The most important information is front-loaded and every sentence earns its place.

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

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

For a simple read-only tool with one optional parameter, this description is complete. It explains what the tool returns, identifies the primary use case, and the schema covers the parameter. The output schema is absent, but the field list in the description compensates well.

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 sole optional parameter 'view' is fully documented in the schema. The description does not add extra parameter semantics, but the schema carries the burden completely, so baseline 3 is fair.

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: 'Get the logged-in user's Canvas profile' and lists the key returned fields. It clearly differentiates from sibling tools, none of which target the user's own profile. The additional 'Useful first call' phrase reinforces its distinct role.

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 provides clear usage context: it is the first call to confirm credentials. It does not name alternatives or explicitly say when not to use it, but the profile scope is unique among the siblings and no exclusion is really needed.

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 declare readOnlyHint=true, so the safety profile is already covered. The description adds that the response includes rubric assessment and grader comments and clarifies the default userId, which is useful beyond the annotation. However, it does not disclose behaviors such as error conditions, whether non-existent submissions cause an error, or the structure of the response.

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

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

The description is two sentences with no filler. It front-loads the core action and return content, then states the one default that affects invocation behavior.

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

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

For a simple read-only getter with a well-described schema, the description is mostly complete: it names the resource, the relevant return content, and the userId default. The only meaningful gap is the lack of guidance distinguishing this tool from sibling list tools, which is handled partially by the word 'single.'

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 50%, with courseId and assignmentId lacking any description. The description does not compensate by explaining these required parameters or their role, and it merely repeats the schema's userId default. The detailed view parameter semantics live in the schema, not the description, so the description adds little parameter 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 uses a specific verb and resource: 'Get a single submission,' which clearly identifies the operation and differentiates it from the sibling list tools. Mentioning 'rubric assessment and grader comments' further specifies the scope of the returned 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?

The description implies when to use the tool—when a single submission is needed—but gives no explicit guidance on alternatives or exclusions. Sibling tools like canvas_list_recent_submissions and canvas_list_missing_submissions exist, yet the description never tells the agent when to prefer them over this one.

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?

The readOnlyHint annotation already establishes the read-only nature. The description adds the active-only default and the need for contextCodes, but does not disclose ordering, pagination, or how the date parameters interact with filtering. This is mildly useful but not comprehensive.

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

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

The description is two short sentences with the core action and required parameter front-loaded. The inline contextCodes example adds clarity without unnecessary length.

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 list tool with five parameters and no output schema, the description provides the essential starting point but leaves the date-range parameters underspecified. The detailed view schema helps, but an agent still lacks enough context about endDate and startDate to confidently use them.

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%, so the description must compensate. It clarifies contextCodes with a required-flag and example, and hints at activeOnly's default, but endDate and startDate remain bare strings with no format, range, or interaction semantics. The description does not fully compensate for the low schema coverage.

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

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

The description states a specific action ('List announcements') and a clear scope ('across one or more courses'), and identifies the required contextCodes input. This makes the tool's purpose unambiguous and distinct from the sibling tools, which target different resources.

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 clear operational context: contextCodes is required and the default behavior is active-only. It does not explicitly compare against alternative tools, but the resource name and required input make the intended use clear enough for an agent.

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 declare readOnlyHint=true, so the description is not required to restate that. It adds useful behavioral context by noting the inclusion of the user's submission inline and the bucket filter support. This goes beyond the annotation and gives the agent a clearer picture of what the tool returns and how it behaves.

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

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

The description is a single, concise sentence that front-loads the core purpose. It avoids redundancy, and every clause adds relevant information. There is no wasted wording.

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?

Without an output schema, the description hints at the return content ('with the user's submission inline') and identifies the bucket filter. It does not mention pagination, error handling, or exact structure, but for a simple read-only list tool, this is largely sufficient. Slight gaps exist but do not hinder 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 50% (only bucket has a description). The description mentions the bucket filter, but does not add meaning to courseId, which is undocumented in the schema. Since the description does not compensate for the missing courseId description and only repeats the bucket filter concept, it provides minimal added value.

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 clear verb ('List') and specific resource ('a course's assignments'), and adds a distinguishing detail ('with the user's submission inline') that separates it from siblings like canvas_list_missing_submissions. This is precise and 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 description does not explicitly state when to use this tool versus alternatives. It mentions the bucket filter, which implies filtering capabilities, but there is no explicit 'when' or 'when not' guidance. Sibling tools like canvas_list_missing_submissions are not referenced, so the agent must infer the appropriate use case.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds the context-scoping behavior ('across selected contexts'). It does not disclose return format, pagination, or how allEvents affects results, but it does not contradict the annotation.

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. Every word contributes to the basic understanding of the 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?

For a 5-parameter tool with no output schema and many siblings, this description is too minimal. It omits date handling semantics, allEvents behavior, default type, and how it differs from canvas_list_assignments.

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%, and the description does little to compensate. It paraphrases contextCodes as 'selected contexts' but leaves endDate, allEvents, and type defaults undocumented.

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

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

States a specific verb ('List'), resource ('Canvas calendar events or assignments'), and scope ('across selected contexts'). However, it does not differentiate from overlapping siblings like canvas_list_assignments or canvas_list_upcoming_events.

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. The overlap with canvas_list_assignments is not addressed, and there are no explicit exclusions or conditions for choosing this tool.

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 declare readOnlyHint=true, which aligns with 'List'. The description does not add behavioral details such as pagination, response format, or side effects. With annotations covering the safety profile, a 3 is appropriate—it adds no additional behavioral context.

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

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

The description is a single, front-loaded sentence that states the core purpose and key parameters. No unnecessary words or filler.

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

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

For a read-only list tool with no output schema and no required parameters, the description is nearly complete. It covers the action and parameters, but does not mention pagination or response shape, which could be relevant. Still, the basic call is clear.

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% (view and filter have descriptions; scope has only enums). The description mentions scope and filter as optional and clarifies filter's context codes, but the schema already provides these details. View is not mentioned, yet its schema description is thorough. The description adds minimal extra value 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 action ('List') and resource ('Canvas inbox conversations'). It implies a plural listing versus the singular sibling canvas_get_conversation, so the purpose is unambiguous and distinguishable.

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

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

The description implies usage by stating it lists inbox conversations, but it does not explicitly mention when to prefer this over canvas_get_conversation or any other alternatives. The context is clear enough for an agent to infer the correct choice.

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 readOnlyHint annotation already communicates that this operation is read-only. The description adds useful behavioral context by stating that only metadata is returned and that downloading requires a separate call, which aligns with the annotation. It does not disclose pagination, authentication, or response shape, but those are not critical given the annotation coverage.

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

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

The description is a single sentence with no wasted words. The core function is front-loaded, and the important distinction from file download is placed parenthetically, making it both concise and easy to parse.

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 list operation, the description covers the core action and the relation to downloading files. However, with no output schema and no parameter documentation, an agent may not know how to use `searchTerm` or `contentTypes` or what fields to expect in the returned metadata, leaving moderate gaps.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It only implicitly maps 'course's files' to the required `courseId` parameter. The optional parameters `searchTerm` and `contentTypes` are entirely unexplained, leaving their meaning and format to inference.

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

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

The description uses a specific verb and resource: 'List a course's files', which immediately identifies the action and scope. The parenthetical 'metadata only' and the pointer to canvas_download_file clearly differentiate this from downloading actual file content, making its purpose unambiguous among the sibling tools.

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

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

The description explicitly tells the agent to use canvas_download_file with the `url` field when file content is needed, which is a clear conditional alternative. It does not, however, describe when to use this list tool versus other list-oriented siblings, though the context is clear enough for most selection scenarios.

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 readOnlyHint annotation already indicates a safe read operation. The description adds useful context about the returned content (grades, scores, term), but does not disclose other behavioral aspects such as pagination or error conditions. This is acceptable given the annotation coverage.

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

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

The description is a single concise sentence that front-loads the action and includes relevant details. Every word adds value, and it is not over-specified.

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 clarifies what the response includes (course-level grades, total scores, current grading period scores, term). For a simple list tool with one optional parameter, this is sufficient; missing details like pagination or ordering are minor.

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 only parameter, observeeId, is fully documented in the schema ('Observed student's user ID; omit for self.'). The description does not add any meaning beyond the schema, so the baseline score of 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 states a specific verb ('List') and resource ('active Canvas courses'), and specifies the included data (grades, scores, term), distinguishing it from sibling tools like canvas_get_course (single course) or canvas_list_assignments (different resource).

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

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

The description implies usage (to list courses) but does not explicitly mention when to choose this tool over alternatives like canvas_get_course or canvas_list_enrollments. No exclusions or alternative conditions are stated.

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

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

The description says 'read-only', which merely repeats the existing readOnlyHint annotation and adds no new behavioral information. It does not disclose filtering behavior, ordering defaults, pagination, what the response contains, or how onlyAnnouncements affects results. The addition of 'for a course' is minimal and already implied by the required courseId 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?

The description is a single front-loaded sentence and is easy to scan. The parenthetical 'read-only' is slightly redundant with the annotation but does not add meaningful bloat, so the structure earns a solid score.

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, no output schema, and low schema description coverage, a one-sentence description is insufficient for correct invocation. An agent is left without details on onlyAnnouncements semantics, orderBy behavior, response shape, or how this list relates to the sibling announcements/conversations 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?

With schema description coverage at only 25%, the description needed to compensate by explaining the parameters, but it only references the course scope. The schema itself documents the view parameter well, but orderBy, courseId, and onlyAnnouncements receive no meaningful semantic explanation anywhere.

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 (List), a clear resource (discussion topics), and a scope (for a course), so an agent can tell what operation is being offered. It does not explicitly differentiate from siblings like canvas_list_announcements, though the resource name itself provides most of the 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?

There is no guidance about when to use this tool versus alternatives such as canvas_list_announcements, canvas_list_conversations, or canvas_list_assignments. The parenthetical 'read-only' describes safety, not usage context, and no exclusions or alternative-tool routing is provided.

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 readOnlyHint annotation already communicates that this is a safe read operation, and the description adds that only 'active' enrollments are returned and includes grading-period context. It does not mention pagination, data volume, permissions, or the significance of the observeeId parameter, but the annotation lowers the burden and the description is not misleading.

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

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

The description is a single focused sentence that front-loads the core action and resource, then adds relevant output details in a parenthetical. There is no fluff, repetition, or unnecessary structure.

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?

Although the tool is simple, the description omits the role of observeeId and the scope of the enrollment listing. An agent could not confidently determine what to pass or whether the call returns enrollments for the current user or a specified observee. The output fields are listed, but invocation semantics are 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?

The input schema only exposes observeeId with no description, and the description does not explain what observeeId means, whether it is required, or what happens when it is omitted. With 0% schema description coverage, the description was expected to compensate, but it only describes the output fields and never addresses the 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 description clearly identifies the action ('List') and the resource ('active student enrollments'), and the parenthetical grade fields add useful specificity that distinguishes it from generic enrollment or course listing tools. However, it does not explicitly differentiate itself from sibling tools such as canvas_list_courses or canvas_list_observees beyond the resource name.

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

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

The description implies usage when an agent needs active student enrollments with grade details, but it provides no explicit when-to-use or when-not-to-use guidance. It does not name alternatives or exclusion criteria, though the purpose is reasonably inferable from the resource and field list.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds meaningful selection context by defining exactly what is returned, but it does not disclose potential behaviors such as pagination, ordering, default course scope when no observee is provided, or whether the list is limited to currently enrolled courses.

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

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

The description is two short sentences with no filler. The primary purpose and scope are front-loaded, and the conditional usage requirement is delivered directly in the second sentence.

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

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

For a simple read-only list tool with only two optional-looking parameters and no output schema, the description covers the core purpose and the most important precondition. It is sufficient for an agent to decide whether to invoke it and to know that courseIds is required for observees.

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 50%: courseIds is documented as required when observeeId is set, and the description reinforces that. observeeId itself has no schema description, leaving only the phrase 'linked observee' to imply its meaning, so the description only partially compensates for the 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 names a specific action and resource: 'List past-due unsubmitted assignments', and adds a scope qualifier ('for the user or a linked observee') that separates it from broader listing tools. It does not explicitly name sibling tools, so it stops short of full differentiation.

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 clearly signals when to use the tool: when the need is for past-due unsubmitted assignments. It also gives the key conditional requirement, 'For an observee, courseIds is required.' It does not explicitly contrast with alternatives like canvas_list_assignments or canvas_list_recent_submissions, so it lacks the strongest routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the empty-array behavior for student tokens, which is useful. It doesn't discuss pagination, rate limits, or response size, but for a read-only list tool this is acceptable.

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 compact and front-loaded with the core purpose. The parameter explanation is detailed but earns its place by clarifying behavior that the schema enum alone doesn't convey.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers the essential behavior. The empty-array note and the view parameter semantics are the main contextual gaps an agent would face, and both are addressed.

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 schema already documents the 'view' parameter. The description adds meaningful detail about what 'compact' vs 'full' actually do (avatar URL removal, link fields surviving, no field projection), which goes beyond the schema's enum labels.

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 ('List') and resource ('students linked to your Canvas observer account'), and adds a clarifying note about the empty-array case for plain student tokens. This clearly distinguishes it from sibling tools like canvas_list_courses or canvas_list_enrollments.

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

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

The description implies when to use it: when you have an observer account and need linked students. It also notes the empty-array behavior for student tokens, which helps an agent know when not to expect results. It doesn't explicitly name alternatives, but the sibling list makes the context clear.

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

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

readOnlyHint=true already covers the read-only safety profile, and the description is fully consistent with it (a 'List' operation). The description adds genuine behavioral context beyond the annotation: it aggregates four item types and supports viewing a linked observee's planner. It does not disclose date-range defaults, pagination, or the new_activity filter's semantics, but the annotation lowers the bar and the added context is meaningful.

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 well-formed sentence that front-loads the verb and resource, uses a parenthetical to enumerate item types, and wastes no words. Every phrase 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 5 parameters, 0% schema coverage, and no output schema, the description is too thin for correct invocation. It omits date format expectations, the semantics of the filter enum, context-code formatting conventions, and what the response contains — all critical for a Canvas API tool.

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

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

Schema description coverage is 0%, so the description carries full responsibility for explaining the five parameters, yet it names none of them. An agent is left guessing at the meaning and format of startDate/endDate, the filter='new_activity' enum value, the observeeId linkage requirement, and how to format Canvas contextCodes.

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 pairs a specific verb ('List') with a concrete resource ('planner items') and explicitly enumerates the aggregated item types (assignments, announcements, planner notes, calendar events). The 'planner' framing plus the observee scope clearly differentiates it from siblings like canvas_list_assignments, canvas_list_announcements, and canvas_list_calendar_events.

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

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

The description implies usage — an agent can infer this is the right tool when it needs a cross-type aggregated planner view, possibly for an observee. However, it never explicitly states when to prefer this over the sibling list tools, names no alternatives, and gives no exclusions or prerequisites (e.g., whether an observee must first be linked).

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 readOnlyHint annotation already covers safety, and the description adds useful behavioral context: the default 14-day window and the scope to the calling user. It does not claim destructive behavior and does not contradict the annotation. Ordering and pagination are not mentioned, but these are not critical for correct invocation.

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 deliver the purpose and the key default behavior with no filler. The main action is front-loaded, making the tool easy to scan and understand quickly.

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?

Combined with the detailed schema, the description gives an agent everything needed to invoke the tool correctly: required courseId, optional since/studentId/view, and a read-only guarantee. There is no output schema, but the view parameter already describes response shape. Slight ambiguity around exactly what 'graded' means keeps this from being fully complete.

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

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

Three of four parameters have detailed schema descriptions: view covers compact/full response shapes, since covers the ISO format and default, and studentId covers 'self' and numeric IDs. courseId is undocumented but self-evident from its name. The description mainly restates the default window already present in the schema, so it adds little parameter-level 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 uses a specific verb ('List') and resource ('recently graded submissions in a course'), and the qualifier 'recently graded' distinguishes it from siblings like canvas_list_missing_submissions. The 14-day default window also makes the tool's scope explicit.

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

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

The description clearly signals when to use the tool: for recently graded submissions in a course. It does not explicitly name alternatives or state when-not-to-use, but the context is clear enough to route an agent away from missing-submission or single-submission tools.

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

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

The annotation readOnlyHint=true already establishes that this is a safe read operation. The description adds useful context by specifying that the results are scoped to the calling user and that the view is 'curated' (Canvas's specific next-7-days filter), which goes beyond the annotation.

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

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

The description is a single, front-loaded sentence ('List the calling user's upcoming events...') that conveys the action, resource, scope, and a clarifying qualifier. There is no wasted wording or unnecessary detail.

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

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

For a zero-parameter read-only tool, the description is sufficiently complete. It states what the tool returns and its scope, and with no output schema, the only ambiguity is the exact event fields returned, which is reasonable to omit for such a simple list tool. A brief mention of the return format could push it higher, but it is not essential.

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 100% schema coverage, leaving nothing for the description to explain. The baseline of 4 is appropriate; the description simply reinforces the tool's purpose without needing to elaborate on inputs.

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 tool lists the calling user's upcoming events, with the specific qualifier 'Canvas's curated next-7-days view'. This distinguishes it from sibling tools like canvas_list_calendar_events or canvas_list_planner_items by specifying a particular resource and time window.

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

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

The description implies when to use the tool—when you need the curated next-7-days view of the user's events—but it does not explicitly mention alternatives or provide exclusion criteria. The guidance is implied rather than explicit.

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