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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds some useful context by framing the result as 'Recent posts' and explaining the days window and course scoping, but it does not disclose ordering, limits, or how the open-world hint affects the returned posts. Overall it provides modest value beyond the annotations.

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

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

The description is two short sentences plus a bulleted argument list, with no filler. The purpose is front-loaded, and each line earns its place by adding either scope or parameter semantics.

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 two optional parameters, an output schema, and readOnly/openWorld annotations, the description is nearly complete. It covers what the tool returns, the time filter, and the course filter. It does not mention ordering or result limits, but the output schema likely captures return structure, so this is a minor gap.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining the parameters. It does this well: 'days: How far back to look' clarifies the time window, and 'course: Limit to one course (code like "CS-214", id, or name)' gives concrete accepted formats that the schema does not provide. It would benefit from specifying the unit for days more explicitly, but it is still genuinely helpful.

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

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

The description states the resource clearly: 'Recent posts in the courses' Announcements (news) forums.' It identifies exactly what the tool returns and distinguishes it from related tools like read_discussion or whats_new, though it does not explicitly name those alternatives. A more explicit verb like 'List' or 'Get' would make it stronger.

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 through the parameter documentation ('How far back to look', 'Limit to one course') but provides no explicit guidance on when to use this tool versus alternatives such as whats_new, read_discussion, or upcoming_deadlines. There are no exclusions or conditions directing the agent to a sibling tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation and may return unexpected/extra data. The description adds the behavior of listing all items in sections, which is useful. However, it doesn't disclose details like pagination, depth of item details, or whether the output is hierarchical. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is concise and front-loaded: the first sentence states the core function, and the Args section provides parameter details. Every sentence earns its place, with no fluff.

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 params, output schema exists), the description is mostly complete. It explains what the tool does, how to specify the course, and how to filter sections. The output schema likely covers return values, so the description doesn't need to. A minor gap: no mention of what happens if the course is not found or if the section filter matches nothing, but this is not critical for a read-only overview tool.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains the 'course' parameter accepts a code, numeric id, or name part, and the 'section' parameter filters by number or name with examples. This adds significant meaning beyond the bare schema. However, it doesn't specify the exact format of the output or how section matching works in edge cases (e.g., partial matches).

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: showing a course's sections and every item in them, with specific examples of item types (files, assignments, pages, links, forums) and ids. This distinguishes it from siblings like list_courses (which likely lists courses) and open_item (which likely opens a specific item).

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

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

The description explains the purpose and the two parameters, including how to specify the course (code, numeric id, or name part) and how to filter sections. It doesn't explicitly state when to use this tool vs alternatives, but the clear scope (course overview vs. list_courses, open_item, etc.) implies the usage context. A small gap: no explicit 'use this instead of X when...' 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?

The readOnlyHint and openWorldHint annotations already cover the safety and non-exhaustiveness profile, so the description is not required to restate them. It adds the output-scope detail that all grade items are returned, but no behavioral quirks like pagination, freshness, or matching ambiguity are 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 compact and front-loaded: one clear summary sentence followed by a single documented arg. Every sentence carries information with no filler.

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

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

For a simple read-only, single-parameter tool with an output schema and safety annotations, the description covers the input format and the returned content adequately. It omits only sibling-selection guidance, which is already penalized under usage guidelines, and ambiguity handling, which is minor for this level of 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?

With 0% schema coverage, the description fully compensates by defining the course parameter as a code, numeric id, or name fragment and giving the CS-214 example. This is materially more useful than the bare string property in the schema, though it doesn't address ambiguous matches.

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

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

The description states the resource (grades) and exactly what it returns: every grade item with score, range, percentage, and feedback, scoped to a course. That clearly conveys an information-retrieval purpose and separates it from announcements or deadlines by content, though it never uses an explicit verb like 'retrieve'.

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

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

There is no guidance on when to use this tool versus siblings such as course_overview or list_courses, and no exclusions or alternatives are named. The only hint is the word 'grades', which weakly implies use when grade details are needed.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context: the result ordering (most recently visited first) and the meaning of hidden courses (ones you don't follow). It could mention more about pagination or response volume, but given the annotation coverage, it exceeds the baseline.

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

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

The description is compact and front-loaded with the primary purpose, followed by one relevant contextual note and a concise Args section. No sentence is wasted, and the structure makes the two optional parameters easy to scan.

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 with two optional booleans and an output schema already present. The description covers ordering, hidden-course semantics, and both parameters. Nothing needed to safely invoke this tool correctly is missing.

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

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

Schema coverage is 0%, so the description bears the full burden of explaining parameters. It does so clearly: include_past ('Also list courses whose end date has passed') and include_hidden ('Also list courses hidden on your dashboard'). Each boolean's effect is explicit, and the word 'Also' implies the default false behavior matching the schema defaults.

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

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

The description states a specific verb ('List'), a clear resource ('courses you're enrolled in'), and a distinctive ordering ('most recently visited first'). It also distinguishes itself from siblings by explaining that hidden dashboard courses are skipped by other tools unless named explicitly, which helps disambiguate from course_overview and similar 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 gives clear context about when this tool is relevant and explains hidden-course semantics relative to other tools ('other tools skip them unless you name them explicitly'). It does not explicitly name sibling alternatives or provide a direct when-to-use versus when-not-to-use comparison, but the context is strong enough for an agent to make a reasonable 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 description discloses important runtime behavior beyond the readOnlyHint/openWorldHint annotations: long PDFs return a page map and require a second call with pages, and max_chars limits file text. It also explains what each item type returns, which is substantial 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 well-structured: a one-line summary, scannable item-type bullets, and an Args section. Every sentence adds useful information, and the long-PDF behavior is front-loaded where it matters most.

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

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

For a read-only opener with seven item types and three parameters, the description covers all relevant behaviors and return shapes. An output schema exists, so detailed return fields need not be repeated. No critical calling context is missing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It fully does: item_id is sourced from specific tool outputs, pages includes concrete format examples like '1-5' and '2,4,10-12', and max_chars is tied to truncation and page-map behavior.

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 opens with a specific verb and resource: 'Open any course item by id and return its content.' The item-type bullets further clarify what each kind of item yields, and references to read_file/read_discussion distinguish it from those sibling tools.

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

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

It states where item_id comes from (course_overview, search, upcoming_deadlines) and gives explicit alternatives for drilling into specific items, e.g., 'read one with read_discussion' and 'read one with read_file.' This gives an agent clear routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context: it returns all posts and orders them oldest first. However, it does not describe pagination, response size limits, or other runtime behaviors. This is comparable to the get_calls calibration where the description adds scoping but not rich behavioral detail.

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: the first states the core behavior, the second documents the parameter source. Every sentence earns its place, and the purpose is front-loaded. No redundant filler.

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

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

For a simple one-parameter read tool with readOnlyHint=true, openWorldHint=true, and an output schema present, the description covers what an agent needs: what the tool does, the ordering behavior, and where to obtain the discussion_id. No critical calling information is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains that discussion_id comes from open_item on a forum or from announcements, which is meaningful context beyond the bare integer schema. It does not fully specify the id format, but the sourcing guidance is sufficient for a single parameter.

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

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

The description opens with a specific verb and resource: 'Read a whole forum thread (all posts, oldest first).' This clearly distinguishes it from siblings like open_item, which likely opens a single item, by emphasizing the full thread scope and ordering.

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 the whole thread is needed—but does not explicitly state alternatives or exclusions. It does provide useful sourcing guidance for the discussion_id, referencing open_item and announcements, which helps an agent locate the parameter value.

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=true annotation, the description discloses concrete behavior: PDFs get a page map for long files, code/text files return as-is, files are saved locally on the user's Mac with the path in output, and max_chars triggers page-map behavior. This is substantial behavioral transparency, exceeding 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 front-loaded with the core action, then gives behaviorally important PDF handling, then parameter details. Every sentence provides useful information; there is no filler or repetition of schema structure.

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

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

Given an output schema is present, return values need not be explained. The description covers all three parameters, behavior for different file types, pagination flow, local saving, and URL provenance. An agent has everything needed to call the tool correctly.

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

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

Schema description coverage is 0%, so the Args section carries the full burden. It explains file_url's expected URL shape, pages formats ('1-5', '2,4,10-12' or 'all'), and max_chars semantics. This compensates completely for the schema's lack of descriptions.

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 opens with a specific verb and resource: 'Download a Moodle file... and return its text.' It clarifies the kinds of files (assignment attachments, folder files) and sources for the URL, which distinguishes it from sibling tools like read_discussion or search_in_files.

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

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

The description gives clear operational guidance: long PDFs return a page map first, then instructs to call again with pages='12-14'. It also specifies where file_url comes from (open_item, search_in_files, read_discussion), providing workflow context. It doesn't explicitly state exclusions or when not to use this tool, but that is not a major gap given the clear file-reading 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds useful behavioral details: matching ignores accents and case, and the default scope is 'all ongoing courses.' However, it does not disclose result pagination, ordering, or behavior when no matches are found, leaving some gaps 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 concise and well-structured. The first sentence states the primary purpose, followed by a one-line note on matching behavior, and then a clean Args section with examples. No fluff or redundancy; every sentence contributes 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?

For a simple two-parameter tool with an output schema, the description is reasonably complete. It covers the search scope, matching rules, and parameter defaults. It doesn't describe the return format, but since an output schema exists, that is not required. The tool's simplicity and annotations cover most operational context, making this a solid score.

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

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

Schema description coverage is 0%, so the description must fully explain the parameters. It provides concrete examples for 'query' (e.g., 'homework 3') and clarifies the 'course' parameter's default and scope (all ongoing courses). It adds meaning beyond the raw schema, though it does not specify the expected format of the course value (e.g., ID vs. name), which would be helpful.

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

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

The description states a specific verb and resource: 'Find course items ... and sections by name across your courses.' It distinguishes from siblings by explicitly limiting to name-based search, which contrasts with search_in_files (likely content search). The purpose is clear and unambiguous.

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

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

The description implies when to use the tool (searching by name, ignoring accents/case, defaulting to ongoing courses) but does not explicitly mention alternatives or when not to use it. No comparison to search_in_files or other siblings is provided, leaving the agent to infer the appropriate context.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses meaningful behavioral details: the first search downloads and indexes files with a latency cost, later searches are instant, and query words must all appear on the same page. This adds real operational context without contradicting the annotations.

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

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

The description is well-structured and front-loaded: the core behavior, return value, and cost are stated first, followed by concise parameter explanations. Every sentence carries information useful for selecting or invoking the tool, with no filler.

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

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

For a search tool with an output schema, the description covers all essential calling context: scope, result shape, indexing tradeoff, and parameter semantics. Nothing an agent needs to decide whether to call it or how to call it 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?

Although the schema has 0% description coverage, the description fully compensates by explaining each parameter: query requires all words on the same page, course limits scope and defaults to all ongoing courses, and max_results controls the number of returned pages. It adds practical meaning and an example that the schema alone lacks.

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 is explicit and specific: it states a clear verb ('full-text search'), a concrete resource ('course files ... and pages'), and the key output (matching pages with a snippet and an exact call to read them). This clearly differentiates it from a generic 'search' tool and from reading whole files.

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 conveys when to use the tool by explaining that it lets the agent read only relevant pages instead of whole files, and recommends limiting to one course. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to route correctly.

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 rich behavioral details beyond the annotations: it writes to a local folder, creates one subfolder per section, produces INDEX.md with links/due dates/item ids, downloads only new or changed files, skips files over a size limit, and explicitly states nothing on Moodle is changed. The annotations (idempotent, non-destructive, not read-only) are consistent with this local-write behavior, so there is no contradiction.

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

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

The description is compact and front-loaded: the core behavior is in the first sentence, followed by a concise behavior summary and a short Args block. Every sentence earns its place; there is no filler or repetition of schema metadata.

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 three parameters and an output schema, the description covers all essential operational aspects: what gets downloaded, where it goes, how re-runs behave, safety, and parameter meaning. The presence of the output schema means not explaining return values is acceptable.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameters. It compensates excellently: course is explained with accepted forms ('CS-214', numeric id, or part of the name), folder gives the default path pattern, and max_file_mb is described with a concrete example ('lecture videos'). This meaningfully exceeds the bare type information in 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 opens with a specific verb and resource: 'Download a course's materials into a local folder, one subfolder per section.' This clearly distinguishes it from sibling tools like read_file, search, and course_overview, all of which serve different purposes. No ambiguity about what this tool does.

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 intended use case (getting a local copy of course materials) is clear from the purpose itself, and the description adds context that it is cheap to re-run and changes nothing on Moodle, implying repeated safe use. However, it does not explicitly contrast with alternatives or state when not to use it, so it stops 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?

Annotations include readOnlyHint and openWorldHint, and the description adds valuable behavioral context beyond that: it defines the 'TODO'/'done' status meaning and notes that include_past_days helps catch overdue work. This clarifies the tool's output semantics without contradicting the annotations.

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

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

The description is concise and well-structured: a lead sentence stating the purpose, a short clarification of the status flag, then a compact Args list. It avoids redundancy and front-loads the core functionality.

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 all parameters, explains the output's status semantics, and mentions a useful use case (catching overdue work). With an output schema present, it does not need to detail return values. It is sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description is the sole source of parameter meaning. It explains 'days' as how far ahead to look, 'course' as a filter by code/ID/name, and 'include_past_days' as a way to include recent past deadlines. This fully compensates for the missing schema descriptions.

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: listing upcoming deadlines from assignments/quizzes and calendar events, plus a status indicator of whether action is needed. It also explains the 'TODO' vs 'done' semantics, making it distinct from siblings like 'course_overview' or 'whats_new'.

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

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

The description explains how to use the arguments and what the tool does, but it does not explicitly state when to use this tool over alternatives or provide exclusion criteria. The intended use case (checking deadlines) is implied but not contrasted with sibling tools.

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

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

The description discloses a non-obvious stateful behavior: the tool remembers the last call time and uses it as the default window, and that passing `since` does not update that marker. This goes well beyond the readOnlyHint and openWorldHint annotations, which only indicate safety and that results may vary. The description also clarifies the first-time fallback, which is exactly the kind of behavioral context an agent needs.

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

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

The description is compact and front-loaded: the first sentence states the purpose, the second explains the default behavior, and the Args section is terse and scannable. Every sentence earns its place, and the parameter documentation is formatted for quick parsing.

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

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

The description is complete for a read-only, two-parameter tool with an output schema present. It explains the stateful default, the parameter semantics, and the scope of results. The only thing not covered is the exact shape of the output, but the output schema exists and the description doesn't need to duplicate it. A small gap is that it doesn't mention whether results are sorted or limited, but that's minor given the 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?

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It does this well: `since` gets format examples and the semantic distinction of not moving the marker, and `course` gets accepted formats (code, id, or name) with an example. The only minor gap is that it doesn't specify what happens if an invalid course is provided, but that's not essential for invoking the tool correctly.

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 opens with a specific verb ('what changed') and enumerates the exact resource types covered: new or edited items and files, new grades, new forum posts. This clearly distinguishes it from siblings like announcements, grades, or read_discussion, which focus on single resource types.

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 explains the default time window behavior and how the 'last check' marker works, including the first-call fallback of 7 days. It also documents the two optional parameters with concrete examples ('3d', '12h', '2w', or a date like '2026-09-20'), and clarifies that using `since` does not move the marker. This is strong when-to-use guidance.

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