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

The destructiveHint annotation already warns of side effects, and the description adds that the URL comes from canvas_list_course_files. However, it does not disclose the overwrite parameter's behavior, whether directories are created, or other filesystem effects. This is partial but not rich 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 two sentences long, front-loaded with the purpose, and contains no fluff. Each sentence adds essential information: the action and the required input constraints.

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?

While the tool is relatively simple and the source of URL is specified, the description does not address the overwrite parameter's effect, the return value (no output schema), or error conditions. The destructive annotation covers safety, but the agent still lacks details about file overwrite behavior, making the description only partially 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 description adds meaning by explaining that 'url' is the absolute URL from canvas_list_course_files, which is helpful. However, it does not explain the 'overwrite' parameter, which has no schema description. With 67% schema coverage, the description partially compensates but leaves a key parameter ambiguous.

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's action ('Download a Canvas file to disk') with a specific verb and resource. It distinguishes this tool from siblings by referencing the source of the URL (canvas_list_course_files), making its purpose 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 provides a clear prerequisite: the 'url' must come from canvas_list_course_files, and 'destinationPath' is required. This guides the agent on how to prepare inputs, though it does not explicitly mention when not to use it or list alternatives. The context is sufficient for correct usage.

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 verb 'Get' is consistent. The description adds the scope 'full thread with all messages', but it does not disclose other behavioral traits such as pagination, message ordering, or potential large payloads. It adds minimal value beyond annotations.

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

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

The description is a single, front-loaded sentence with no waste. Every word contributes to understanding the tool's purpose.

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 tool with one parameter and no output schema, the description should at least explain what the id is and what the response contains. It only states the high-level purpose, leaving essential usage details unaddressed. The presence of annotations reduces the burden slightly, but significant gaps remain.

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 has one parameter 'id' with no description, and the description also provides no explanation of what the id refers to. With 0% schema description coverage, the description must compensate but fails to clarify even that it is the conversation ID. This leaves the agent guessing.

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 ('Get') and the resource ('full Canvas conversation thread with all messages'), which distinguishes it from sibling 'canvas_list_conversations' that likely returns summaries. The scope 'full' and 'all messages' adds specificity.

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 this tool is for fetching a specific conversation thread in full, but it does not explicitly state when to use it over alternatives like canvas_list_conversations. No exclusions or alternative guidance is provided, though context makes the use case reasonably 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?

The readOnlyHint annotation already signals a safe read operation. The description adds value by specifying what data is returned (syllabus, teachers, term), which is useful behavioral context. It does not disclose other traits, but for a simple get, this is sufficient.

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 that is front-loaded with the action and resource, followed by included content. There is no wasted or redundant text.

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

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

For a simple single-parameter get tool with readOnly annotation and no output schema, the description fully covers the purpose, the returned data, and the parameter implicitly. No additional details are necessary.

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 schema has only one parameter, courseId, with no description coverage. The tool name and parameter name make its meaning self-evident, but the description does not explicitly explain the parameter or its format, so it adds no additional semantics beyond what the schema already implies.

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 retrieves a single Canvas course, using a specific verb ('Get') and resource, and adds the included content (syllabus, teachers, term). This distinguishes it from sibling tools like canvas_list_courses and other get 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 implicitly conveys when to use this tool (when a specific course is needed) and the 'single course' phrasing differentiates it from list_courses. However, it does not explicitly mention alternatives or when not to use it, lacking exclusions.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds value by listing the returned fields and noting it serves as a credential confirmation, which is useful behavioral context 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 two sentences long with no unnecessary words. The first sentence states the purpose and output fields, while the second provides a clear usage recommendation. Every word earns its place.

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

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

For a zero-parameter, read-only tool with no output schema, the description fully covers purpose, return fields, and an explicit use case. There are no gaps in what an agent needs to know to select and invoke this 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?

This tool has zero parameters and the schema coverage is 100%, so the description does not need to explain parameter semantics. The baseline for zero-parameter tools is 4, and the description appropriately focuses on the output rather than 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 uses the specific verb 'Get' and identifies the resource as 'the logged-in user's Canvas profile', then enumerates the exact fields returned. This clearly differentiates it from sibling tools that list or fetch other resources like submissions, courses, or conversations.

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

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

The phrase 'Useful first call to confirm credentials' provides an explicit when-to-use context, suggesting it should be called before other operations to verify authentication. No alternatives are needed since there is no other profile-related tool among siblings.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds valuable behavioral context about the return contents (rubric assessment, grader comments) and the userId defaulting to 'self', going 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?

The description is one concise sentence that front-loads the core action. Every word earns its place, with no redundant detail.

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

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

For a simple read-only tool with annotations, the description covers the essential aspects: what it returns and a key default behavior. No output schema exists, but the description sufficiently clarifies the tool's purpose and basic behavior for straightforward usage.

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 33%, so the description must compensate for the undocumented courseId and assignmentId. It partially does by explaining the userId default, but the other two parameters remain semantically under-specified. The description adds some value but does not fully cover 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 uses a specific verb ('Get') and resource ('single submission'), clearly distinguishing it from the sibling list tools. It also specifies what the submission includes (rubric assessment and grader comments), making the purpose unmistakable.

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 this tool is for fetching one specific submission rather than listing multiple submissions, but it does not explicitly mention alternatives or provide when-not-to-use guidance. The context is clear enough but lacks explicit exclusions or alternative tool references.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds valuable behavioral details: it makes exactly one authenticated request, reports the credential source and round-trip time, and never returns the credential itself. It also explains the three outcome categories it distinguishes, which is genuinely useful.

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

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

Three sentences, all informative and none redundant. The core purpose is stated first, followed by output reporting details and a clear call-to-use trigger. The structure is 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?

Given no parameters and no output schema, the description covers what an agent needs: what the tool does, what signals it returns, when to call it, and a critical safety detail (no credential leakage). This is complete for the tool's complexity.

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, so the description cannot add parameter-level meaning. The baseline of 4 applies because no parameter documentation burden exists; the description appropriately focuses on behavior instead.

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 a specific diagnostic action: resolve the credential, make one authenticated request, and report which hop failed. It distinguishes itself from the sibling data-retrieval tools by framing this as a healthcheck rather than a data operation.

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 says 'Call this when a real tool fails and you want to know which hop broke,' giving clear usage context. It does not explicitly name when-not-to-use cases or alternative tools, but such exclusions are not necessary given the tool's unique diagnostic role.

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 declares safety, and the description adds that contextCodes is required and the default is active-only. No contradictions, but it omits behavior like pagination or return format.

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 one sentence with an inline code example, front-loaded with the verb and resource. No 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?

The tool has no output schema and low parameter coverage. The description doesn't explain the date range parameters or the activeOnly flag's semantics, so an agent would be under-informed about how to 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 coverage is only 25% (contextCodes). The description provides an example format for contextCodes, but startDate, endDate, and activeOnly are not explained beyond the default mention. This is insufficient for those parameters.

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

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

The description clearly states the action ('List announcements') and the scope ('across one or more courses'), effectively identifying the resource. It does not explicitly compare to sibling tools, so it's clear but not fully 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?

It mentions that contextCodes is required and defaults to active-only, giving some usage context. However, it does not state when to prefer this tool over alternatives like calendar events or discussions, nor does it provide exclusions.

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

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

The annotations already declare readOnlyHint=true, so the read-only nature is established. The description adds value by mentioning 'with the user's submission inline' and 'standard Canvas bucket filter', which give some context about the response content and parameter behavior. However, it does not disclose other behavioral traits like pagination, rate limits, or the exact format of inline submissions. Given the annotation coverage, this is acceptable but not exceptional.

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 immediately conveys the core action and key qualifier. The second clause adds the bucket filter without redundancy. Every word contributes, and it is appropriately sized for the tool's simplicity.

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 tool with a readOnlyHint annotation and clear required parameter, the description is largely complete. It captures the purpose, the inclusion of submission inline, and the optional filter. Since there is no output schema, it does not need to detail return values, but the brief mention of 'inline' is a helpful hint. The lack of usage guidance slightly reduces completeness, but overall it provides sufficient context for an agent to understand what the tool does.

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 only 'bucket' having a schema description. The description reinforces 'bucket' as a standard Canvas filter, adding slight clarification, but provides no additional meaning for 'courseId'. The parameter names are self-explanatory, yet the description does little to compensate for the missing schema description on courseId or to explain how the bucket filter interacts with the results. This is a middle-ground score.

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 'List a course's assignments' with the specific qualifier '(with the user's submission inline)', which distinguishes it from sibling tools like canvas_list_missing_submissions. The verb 'List' and resource 'assignments' are precise, and the optional bucket filter is mentioned, making the purpose 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 provides no explicit guidance on when to use this tool versus alternatives like canvas_list_missing_submissions or canvas_list_recent_submissions. It only mentions the bucket filter feature, but does not state context such as 'use when you need assignment details with the user's submission' or exclude other scenarios. This leaves the agent without clear selection criteria.

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 state readOnlyHint=true, so the tool is a safe read operation. The description adds that results are scoped to selected contexts, but does not disclose return format, pagination, or how the 'type' parameter filters events vs assignments. No contradiction with annotations.

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

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

The description is a single, concise sentence that front-loads the main verb and resource. It is not bloated, but it is somewhat minimal and does not make full use of the available space to add useful context.

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, no output schema, and only a terse one-sentence description, the tool is under-documented. The description gives a high-level purpose but lacks necessary context about parameter combinations, default behavior, return value structure, and edge cases.

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%, with only startDate and contextCodes having descriptions. The tool description does not explain the 'type', 'endDate', or 'allEvents' parameters, and only loosely hints at contextCodes via 'selected contexts'. It fails to compensate for the schema 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?

The description clearly states the tool lists Canvas calendar events or assignments for selected contexts. It distinguishes the resource as calendar-related, though it does not explicitly contrast with sibling tools 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 is given on when to use this tool versus alternatives. The phrase 'across selected contexts' implies the use of contextCodes, but there are no explicit exclusions, prerequisites, or alternative recommendations.

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 include readOnlyHint=true, so the safety profile is covered. The description adds that scope/filter are optional but does not disclose other behavioral details like pagination, ordering, or return format. With the annotation carrying the main safety burden, this is acceptable but not rich.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the primary action and summarizes the parameters efficiently.

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 two optional parameters, a read-only annotation, and no output schema, the description gives a brief overview but omits details like pagination, default scope, or what a returned conversation object looks like. It is minimally viable but lacks full context.

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 essentially restates the schema: scope enum values are already in the schema, and filter's description already provides the format. Schema description coverage is 50%, but the description adds little meaning beyond what the schema already gives, so it fails to compensate.

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 Canvas inbox conversations with a specific verb+resource. It distinguishes from canvas_get_conversation by the list vs get aspect, though it does not explicitly name the sibling alternative.

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 mentions optional scope and filter parameters but provides no guidance on when to use this tool versus alternatives such as canvas_get_conversation or other list tools. There is no explicit context for when this tool is the right 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 annotation readOnlyHint=true already signals a safe read operation. The description adds the key behavioral constraint that only metadata is returned and directs the agent to the url field for downloading, giving context beyond the annotation without contradicting it.

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

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

The description is a single, front-loaded sentence with a parenthetical that adds crucial differentiation. Every word earns its place; no fluff or redundancy.

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 core purpose and points to an alternative, but with 3 parameters, 0% schema coverage, and no output schema, it lacks explanation of filter semantics and return structure. It is minimally viable but leaves gaps for an agent trying to use the tool effectively.

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 schema has 0% description coverage, so the description must compensate for parameter meanings. It does not explain courseId, searchTerm, or contentTypes at all; the only param mention is the `url` field in the context of the sibling download tool, not this tool's parameters. The property names are somewhat self-explanatory, but the agent gets no enrichment from the description.

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 a course's files, specifies 'metadata only' to distinguish from file downloads, and directly names the sibling canvas_download_file for content retrieval. This makes the purpose specific and distinct from related 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 indicates when to use this tool (to list metadata) and when to use an alternative ('use canvas_download_file with the `url` field'), providing clear usage guidance and a named alternative.

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 signals a safe read operation, and the description adds value by specifying exactly what data is returned. However, it does not disclose other behavioral aspects such as pagination, ordering, or any filters beyond the observeeId 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, concise sentence that packs in the resource, filter (active), and returned fields. Every word earns its place with no redundancy.

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 tool with one optional parameter and readOnly annotations, the description adequately covers the purpose and return scope. It is missing potential details like ordering or pagination, but these are not critical for basic usage.

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 single parameter observeeId is fully described in the schema with 'Observed student's user ID; omit for self.' The tool description adds no additional parameter context, but because schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') and identifies the resource ('active Canvas courses') along with the included data (grades, total scores, grading period scores, term). This clearly differentiates it from siblings like canvas_get_course and 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 usage for retrieving active courses with grade information, but it does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool names are mentioned.

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 repeats the 'read-only' annotation without adding additional behavioral context. It does not mention pagination, default ordering, or the behavior of the 'onlyAnnouncements' filter, which would be valuable 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 sentence, which is concise, but it contains redundant information ('read-only') that is already in the annotations, and it omits useful parameter details. It is not overly verbose, but it is under-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?

For a list tool with three parameters and no output schema, this description is incomplete. It leaves the agent without information about the enum values for orderBy, the semantics of onlyAnnouncements, or the structure of the response, making it hard to select and invoke the tool correctly in varied contexts.

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 schema has 0% description coverage, and the tool description does not explain any of the three parameters (courseId, orderBy, onlyAnnouncements). For example, it does not clarify that orderBy accepts position, recent_activity, or title, or what onlyAnnouncements does.

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 ('discussion topics for a course'), making the tool's function clear. However, it does not explicitly distinguish from the sibling tool 'canvas_list_announcements', which may overlap in functionality.

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 no guidance on when to use this tool versus its siblings, such as 'canvas_list_announcements'. There is no mention of filtering by announcements or ordering, nor any exclusions.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds that only 'active' enrollments are included, which is useful behavioral context. However, it does not disclose return format, filtering details, or any other behavioral traits beyond what the annotation and field list imply.

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

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

The description is a single, focused sentence that is front-loaded with the action and resource. It avoids redundancy and includes specific grade fields without unnecessary elaboration.

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 tool is simple (one optional parameter, no output schema), and the description names the returned grade fields, which helps set expectations. However, it omits the meaning of observeeId and any default behavior when the parameter is absent, leaving a noticeable gap in completeness.

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 schema has no description for observeeId, and the tool description does not explain it either. With 0% schema description coverage, the description should compensate and clarify the meaning and behavior of the single parameter, but it fails to do so.

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 active student enrollments with per-course grades, naming specific fields. This distinguishes it from sibling tools like canvas_list_missing_submissions or canvas_list_assignments, which serve different purposes.

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 is provided on when to use this tool versus alternatives. The optional observeeId parameter is ambiguous — it is unclear whether omitting it returns enrollments for all students or something else, and no context or prerequisites are mentioned.

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 discloses behavioral specifics beyond the readOnlyHint annotation: it targets past-due unsubmitted assignments, and it can operate on a linked observee. It also surfaces the conditional requirement for courseIds. The readOnlyHint is respected and the description adds meaningful context about the operation's 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?

The description is two sentences long, with the main purpose front-loaded and the conditional observee requirement placed second. Every word earns its place; there is no filler or redundancy.

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 tool with only two optional parameters and no output schema, the description covers the essential functionality and a key edge case. It does not describe return format or pagination, but these are not critical for a simple listing operation and the readOnlyHint provides safety context.

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 explains the relationship between observeeId and courseIds ('For an observee, courseIds is required'), which adds useful conditional meaning. However, it does not elaborate on what observeeId itself represents beyond 'a linked observee', and schema coverage is only 50%, so the description only partially compensates for the underexplained observeeId 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 states the tool's function with a specific verb ('List') and resource ('past-due unsubmitted assignments'), and identifies the primary user context ('for the user (or a linked observee)'). This distinguishes it from siblings like canvas_list_recent_submissions (which lists recent submissions) and canvas_get_submission (which retrieves a single submission).

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 context for use (finding past-due unsubmitted work) and an explicit prerequisite for observees ('For an observee, courseIds is required'). However, it does not name alternative tools or explicitly state when not to use this tool, leaving some inference to the 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?

The readOnlyHint annotation already indicates a safe read operation. The description adds a useful behavioral nuance—returning an empty array for plain student tokens—which goes beyond the annotation without contradicting it.

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 first sentence states the exact purpose, and the second adds an important edge case. Well-structured and front-loaded.

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

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

For a zero-parameter list tool, the description covers the core purpose and a notable edge case. Since there is no output schema, a slightly richer description of the returned student objects could be helpful, but it is not critical for such a simple 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?

The tool has zero parameters, so per the rubric the baseline is 4. The description correctly focuses on behavior rather than parameter details, which is appropriate here.

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

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

The description uses a specific verb ('List') and a clear resource ('students linked to your Canvas observer account'), distinguishing it from sibling list tools like canvas_list_enrollments or canvas_list_courses. It also clarifies the function of the tool name 'observees'.

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 clear context that the tool works with observer accounts and usefully mentions the plain student token edge case. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.

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

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

The annotations already provide readOnlyHint=true, so the safety profile is known. The description adds no additional behavioral context such as pagination, ordering, date range handling, or behavior when no observeeId is provided. The 'user or a linked observee' scope is also visible in the observeeId parameter. No meaningful behavioral information beyond the annotation is disclosed.

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 with the action verb 'List' front-loaded and the resource immediately clarified in parentheses. Every word contributes meaning, with no wasted text or redundant 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?

Despite being a read-only list tool, it has multiple optional filters (date range, filter enum, contextCodes) that could affect results, but no explanation of their semantics or defaults. There is no output schema, so the description should at least hint at return format or behavior, but it does not. The tool aggregates multiple item types, increasing the need for clarity on scope and filtering, which is missing.

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

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

The schema has 5 parameters with no descriptions (0% schema coverage), and the description provides no parameter explanations. The only hint is 'for the user or a linked observee' which loosely relates to observeeId, but startDate, endDate, filter, and contextCodes are completely unexplained. The description fails to 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 clearly identifies the resource as 'planner items' and parenthetically lists the constituent types (assignments, announcements, planner notes, calendar events), distinguishing it from sibling tools that target a single type. The scope 'for the user or a linked observee' is also stated. It could be more explicit about how it differs from the individual list tools, but the verb+resource+scope is specific enough for a 4.

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 this tool should be used when a combined view of multiple item types is needed, but it does not explicitly state when to use it over calling list_assignments, list_announcements, or list_calendar_events separately. There are no exclusions or alternative tool names given. The usage context is only implied by the parenthetical, not stated as 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 provide readOnlyHint=true, so safety is covered. The description adds useful behavioral context by specifying the default 14-day window and that it applies to the calling user, 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?

Two concise sentences with no redundancy. The main action and default behavior are front-loaded, and every word adds value.

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?

Given the lack of an output schema, the description provides enough for a simple list tool: purpose, default time window, and caller scoping. It omits details like return format or pagination, but these are not critical for this straightforward read operation.

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 67% (since and studentId are described, courseId is not). The description does not add parameter-specific meaning; the '14-day window' simply restates the 'since' parameter's existing schema description.

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 identifies the exact resource ('recently graded submissions') and scope ('in a course'). It also notes the 14-day default window, which clearly distinguishes it from siblings like canvas_list_missing_submissions.

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 use for recent graded submissions but does not explicitly name alternatives or state when not to use it. Context suggests differentiation from missing-submissions and individual-submission tools, but no explicit guidance is 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?

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.