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

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: the file is saved to a default location (Downloads folder) or custom path, and it returns specific details (local file path, filename, size, content type). However, it lacks information on error handling, authentication needs, rate limits, or file overwriting behavior, which are important for a download operation.

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 appropriately sized and front-loaded, starting with the core purpose and key parameters. Each sentence adds value, such as examples, default behavior, return values, and usage context. It could be slightly more concise by combining some details, but overall it's efficient with no wasted text.

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

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

Given the tool's complexity (a file download operation with no annotations and no output schema), the description is moderately complete. It covers the purpose, parameters, and return values, but lacks details on error cases, security considerations, or performance aspects. Without an output schema, more explicit return format details would enhance 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?

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value beyond the schema by reinforcing the URL format with examples and noting the default save path, but it doesn't provide additional semantic context or usage nuances for the 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 specific action ('Download a file') and resource ('from D2L Brightspace'), with explicit examples of what can be downloaded (lecture slides, assignment files, course materials). It distinguishes this tool from sibling tools that retrieve information (e.g., get_announcements, get_assignments) by focusing on file retrieval rather than metadata or content listing.

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 context for when to use this tool ('to download lecture slides, assignment files, course materials, or any file linked in course content'), but it does not explicitly mention when not to use it or name alternatives. For example, it doesn't clarify if this is for files only versus other content types that might require different 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?

No annotations are provided, so the description carries the full burden. It discloses behavioral traits like the return format (title, body, etc.) and that it fetches from instructors, but lacks details on permissions, rate limits, or whether it's read-only. This is adequate but has gaps, such as not specifying if it requires authentication or handles errors.

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

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

The description is front-loaded with the core purpose, followed by return details and usage examples, all in two efficient sentences with zero waste. Every sentence adds value, such as clarifying the return fields and providing query examples, making it highly concise and well-structured.

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 tool's low complexity (1 optional parameter, no output schema, no annotations), the description is mostly complete: it covers purpose, returns, and usage context. However, it lacks output schema details (e.g., response structure) and behavioral aspects like error handling, which slightly reduces completeness for a tool with no annotations.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter (orgUnitId) with its optional nature and env var fallback. The description adds no parameter-specific information beyond what the schema provides, resulting in a baseline score of 3, as it doesn't compensate but also doesn't detract.

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 specific action ('Get course announcements/news items from instructors') and resource ('announcements/news items'), distinguishing it from siblings like get_assignments or get_course_content. It explicitly lists the returned fields (title, body, created date, etc.), making the purpose highly specific and 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?

The description provides clear context by listing example queries ('Any new announcements?', 'What did the professor post?', etc.) that indicate when to use this tool. However, it does not explicitly state when not to use it or name alternatives among siblings, such as get_course_content for general course materials, which prevents a perfect score.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates this is a read operation ('Get') and mentions what information is returned, but doesn't address potential limitations like authentication requirements, rate limits, error conditions, or what happens if the assignment doesn't exist. The description adds some value but leaves important behavioral aspects unspecified.

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 perfectly concise with two sentences that each earn their place. The first sentence states the purpose and scope, while the second provides crucial usage guidance. No wasted words or redundant 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?

For a read operation with 2 parameters and 100% schema coverage, the description provides good context about what information is returned and when to use the tool. However, without annotations or an output schema, it could benefit from more detail about the return format or potential limitations. The description is mostly complete but has minor 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?

With 100% schema description coverage, the schema already documents both parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. The baseline score of 3 is appropriate when the schema does all the parameter documentation work.

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 verb ('Get') and resource ('full details about a specific assignment'), specifying what details are included (instructions, due date, point value, etc.). It distinguishes from sibling 'get_assignments' by indicating this is for detailed information about one specific assignment rather than a list.

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 states when to use this tool ('Use after get_assignments when you need more detail about one assignment'), providing clear context and naming the specific alternative tool. This gives the agent perfect guidance on tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the return format (e.g., ISO 8601 dates, specific field mappings like CustomInstructions.Text) and hints at functionality (e.g., comparing dates to find upcoming/overdue items). However, it doesn't mention potential limitations like pagination, rate limits, or authentication requirements, leaving some behavioral aspects uncovered.

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

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

The description is front-loaded with the core purpose and return details, followed by usage examples. While slightly verbose due to the list of example queries, each sentence adds practical value for an AI agent, and there's no redundant 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?

Given no annotations and no output schema, the description does a good job of explaining the return structure and usage context. However, it could be more complete by addressing potential edge cases (e.g., what happens if no assignments exist) or linking more explicitly to sibling tools beyond get_assignment_submissions.

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 description coverage is 100%, so the baseline is 3. The description adds value by explaining the optionality of orgUnitId (implied through the example queries that don't require it) and its relationship to the D2L_COURSE_ID env var, providing context beyond the schema's technical specification.

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 specific action ('List all assignments for a course') and the resource ('assignments'), distinguishing it from siblings like get_assignment (singular) and get_assignment_submissions. It explicitly lists the returned fields and their purposes, making the tool's function 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 explicit usage scenarios with example queries ('What assignments do I have?', 'What's due this week?', etc.), guiding when to use this tool. It also distinguishes from siblings by noting that the returned Id is needed for get_assignment_submissions, clarifying the relationship between 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what data is returned (submitted files, timestamps, feedback, grades), which is useful, but it does not cover aspects like authentication needs, rate limits, error conditions, or whether it's read-only (implied by 'Get' but not explicit). The description adds value but lacks comprehensive behavioral traits.

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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by a list of data returned and example use cases. Every sentence earns its place by adding clarity and context without redundancy, making it efficient and well-structured.

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 tool's moderate complexity (2 parameters, no output schema, no annotations), the description is mostly complete: it explains what the tool does, what data it returns, and when to use it. However, it lacks details on output format (e.g., structure of returned data) and behavioral aspects like error handling, which would enhance completeness for a tool with no annotations or output schema.

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 description coverage is 100%, so the schema already documents both parameters (orgUnitId and assignmentId) with descriptions. The description does not add any parameter-specific details beyond what the schema provides, such as explaining how assignmentId relates to get_assignments. Baseline 3 is appropriate as the schema handles the heavy lifting.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('user's submissions for an assignment'), and it distinguishes from siblings like get_assignments (which lists assignments) or get_my_grades (which shows overall grades) by focusing on submission details for a specific assignment.

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 context for when to use this tool by listing example questions it can answer (e.g., 'Did I submit this assignment?', 'What grade did I get?'), which implicitly guides usage. However, it does not explicitly state when not to use it or name alternatives among siblings, such as get_my_grades for broader grade overviews.

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?

No annotations are provided, so the description carries the full burden. It describes the return format ('module titles, descriptions, topic names with URLs, and linked assignments'), which is helpful. However, it lacks details on permissions, rate limits, or error handling, leaving behavioral gaps for a read operation.

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 well-structured and front-loaded with the core purpose, followed by return details and usage examples. Every sentence adds value without redundancy, making it efficient 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?

Given the tool's complexity (retrieving structured course data) and lack of annotations or output schema, the description does a good job covering purpose, usage, and return format. However, it could improve by addressing potential limitations or dependencies (e.g., course availability).

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by implicitly clarifying the parameter's role in retrieving course content, though it doesn't explicitly mention the orgUnitId parameter. This elevates the score slightly above the baseline.

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

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

The description clearly states the tool's purpose with specific verbs ('Get the complete course syllabus/structure') and resources ('modules, topics, lectures, and learning materials'). It distinguishes from siblings like get_course_module (single module) and get_course_modules (list of modules) by emphasizing comprehensive content retrieval.

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 provides usage guidelines by listing example queries ('What's in this course?', 'Show me the syllabus', etc.) that indicate when to use this tool. It implicitly distinguishes from alternatives like get_assignments (specific assignments) or get_announcements (announcements only) by focusing on overall course structure.

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?

No annotations are provided, so the description carries the full burden. It describes the behavior of retrieving contents, but lacks details on permissions, rate limits, pagination, or error handling. It adds some context about what is included (child topics, etc.), but more behavioral traits would improve transparency.

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, front-loaded with the core purpose and followed by usage guidance. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding.

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 annotations and no output schema, the description provides basic purpose and usage but lacks details on return values, error cases, or advanced behavioral aspects. It's adequate for a simple read operation but could be more complete for a tool with potential complexity in nested content retrieval.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (orgUnitId and moduleId) well. The description does not add any parameter-specific details beyond what the schema provides, such as examples or usage notes, so it meets the baseline for high 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 states the verb ('Get') and resource ('all contents within a specific course module/section'), specifying what is retrieved (child topics, sub-modules, materials). It distinguishes from siblings like get_course_modules (which lists modules) and get_course_content (which might cover broader content).

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 provides clear context on when to use ('to explore one section of the course in detail'), but does not explicitly mention when not to use or name alternatives. For example, it doesn't contrast with get_course_topic or get_course_content, though the context implies it's for detailed module exploration.

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?

No annotations are provided, so the description carries the full burden. It discloses the return values (module names, descriptions, and ModuleIds) and the tool's purpose as a read operation. However, it lacks details on permissions, error handling, pagination, or rate limits, which are important for a tool with no 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 concise and well-structured with two sentences: the first states the purpose and return values, and the second provides usage guidance. Every sentence adds value without redundancy, making it easy to 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?

Given no annotations and no output schema, the description partially compensates by listing return values. However, for a tool with one parameter and no structured behavioral hints, it lacks details on error cases, authentication needs, or output format specifics, leaving gaps 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 description coverage is 100%, with the parameter 'orgUnitId' fully documented in the schema. The description adds no additional parameter information beyond what the schema provides, such as examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.

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 purpose: 'Get the main sections/modules of a course' specifies the verb (get) and resource (course modules). It distinguishes from siblings like 'get_course_content' by focusing on high-level sections rather than detailed content, though it doesn't explicitly name alternatives. The mention of 'high-level overview' helps differentiate it from more granular 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 provides implied usage guidance: 'Use for a high-level overview of course organization' suggests when to use this tool. However, it doesn't explicitly state when not to use it or name specific alternatives like 'get_course_content' or 'get_course_module' (singular), leaving some ambiguity about sibling tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates this is a read operation ('Get details') and mentions the relationship with get_course_content, but doesn't describe error conditions, authentication requirements, rate limits, or what happens when parameters are invalid. It provides basic context but lacks comprehensive behavioral details.

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 perfectly concise with two sentences that each serve distinct purposes: the first explains what the tool does and what information it returns, the second provides crucial usage guidance. Every word earns its place with zero wasted text.

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

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

For a read operation with 2 parameters (100% schema coverage) and no output schema, the description provides good context about what information is returned and when to use the tool. However, without annotations or output schema, it could benefit from more detail about the return format or error handling. The workflow guidance with get_course_content is particularly valuable.

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 100% schema description coverage, the schema already documents both parameters thoroughly (orgUnitId as course ID with environment variable fallback, topicId as TopicId from get_course_content with example). The description doesn't add any parameter-specific information beyond what's in the schema, so the baseline score 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 clearly states the specific action ('Get details') and resource ('a specific course topic/lecture/reading'), listing the exact information returned (title, description, URL, linked assignments). It distinguishes from siblings like get_course_content by focusing on detailed information about a single item rather than listing content.

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 explicit guidance on when to use this tool ('Use after get_course_content to get more info about a specific item'), creating a clear workflow relationship with a sibling tool. This tells the agent exactly when this tool is appropriate versus alternatives.

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

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

With no annotations provided, the description carries the full burden. It discloses the return format (course details like name, code, dates) and hints at behavioral context by noting the org unit ID is 'needed for other tools'. However, it lacks details on permissions, rate limits, or error handling, leaving gaps for a mutation-free tool.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by return details and usage examples. Every sentence adds value without waste, making it efficient and well-structured for quick comprehension.

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 tool's simplicity (0 parameters, no output schema, no annotations), the description is nearly complete: it covers purpose, return values, and usage context. A minor deduction is for lacking explicit mention of any limitations or error cases, though this is less critical for a read-only list 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 input schema has 0 parameters with 100% coverage, so the baseline is 4. The description adds no parameter information, which is appropriate here as no parameters exist, maintaining clarity without redundancy.

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 specific verb ('List') and resource ('courses you're enrolled in'), distinguishing it from siblings like get_announcements or get_assignments. It provides concrete examples of questions it can answer, 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 explicitly lists use cases ('Use to answer...') that guide when to invoke this tool, such as for enrollment queries or finding course IDs. However, it does not specify when not to use it or mention alternatives among siblings, which prevents a perfect score.

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?

No annotations are provided, so the description carries the full burden. It discloses that it returns grade items with specific details, which is useful, but lacks information on permissions, rate limits, or error handling. The description doesn't contradict any annotations, but could be more detailed for a tool with no annotation support.

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

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

The description is front-loaded with the core purpose, followed by details on returns and usage examples, all in two sentences with zero waste. Every sentence adds value, making it efficient and well-structured for quick understanding.

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 annotations and no output schema, the description does well by detailing what is returned (grade items with specific fields) and when to use it. However, it could improve by mentioning potential limitations or response format, but it's largely complete for a read-only tool with one parameter.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by implying the tool fetches grades for 'a course', which aligns with the 'orgUnitId' parameter being a course ID, and mentions it's optional if an environment variable is set, providing practical context 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 verb ('Get') and resource ('your grades for a course'), specifying it returns all grade items with detailed components like name, scores, percentage, and feedback. It distinguishes from siblings like 'get_assignment' or 'get_assignments' by focusing on personal grades rather than general assignment 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?

It explicitly lists when to use this tool with example questions ('What are my grades?', 'What's my score on the quiz?', etc.), providing clear context for usage. No alternatives are mentioned, but the examples effectively guide when this tool is appropriate, making it comprehensive for its purpose.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by specifying the default time range (7 days back, 30 days ahead) and the types of data returned (events, due dates, associated entities). However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions, leaving some behavioral aspects uncovered.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by return details, defaults, and usage examples. Every sentence adds value without redundancy, and the structure efficiently guides the agent from what the tool does to how to apply it, making it highly concise and well-organized.

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 tool's moderate complexity (3 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage, defaults, and return data. However, without an output schema, it could benefit from more detail on the return format (e.g., structure of 'associated entity'), and the lack of annotations means some behavioral aspects like safety or performance aren't 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 description coverage is 100%, so the schema already documents all parameters (orgUnitId, daysBack, daysAhead) with their types and defaults. The description adds value by explaining the overall time range context ('within a time range') and default values, but doesn't provide additional semantic details beyond what the schema offers, meeting the baseline for high 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 states the tool's purpose with specific verbs ('Get calendar events and due dates') and resources ('for a course within a time range'), distinguishing it from siblings like get_assignments or get_announcements by focusing on time-bound event retrieval. It explicitly lists what information is returned (event title, dates, entity type, course name), making the scope 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 explicit usage guidance by stating 'By default returns events from 7 days ago to 30 days ahead' and giving concrete examples of when to use it (e.g., 'What's due this week?', 'When is the assignment due?'). This clearly defines the tool's context and distinguishes it from siblings that might handle static data like get_assignment or get_my_grades.

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