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

No annotations are present, so the description carries the full burden. It discloses post ordering, pagination behavior via limit/offset, the exact return shape, the Taipei time format, and the fact that credentials come from MCP settings headers. That is a thorough behavioral profile for a read-only resource.

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 purpose, then efficiently covers ordering/pagination, return format, and credential handling. Every sentence contributes operational information and there is no filler 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?

Without an output schema, the description carefully documents the returned JSON and the timestamp format. It also states the dependency on list_announcements. Given only three parameters and a straightforward read operation, this is complete enough for an agent to select and 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 100%, so baseline is 3. The description adds useful value by noting that limit/offset paginate long threads. It also reinforces the relationship between discussion_id and list_announcements, though that is already in the schema. Just enough added meaning to go above 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 opens with a clear action and resource: 'Open ONE announcement and read its thread — the original post plus any replies — given a discussion_id from list_announcements.' This distinguishes it from siblings like list_announcements and get_notifications by specifying it retrieves one conversation thread, not 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 gives clear usage context by tying the input to a discussion_id from list_announcements. It tells the agent when the flow is list first then read, but it does not explicitly list alternatives or say 'when not to use this tool.' Clear context, no exclusion statement.

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, and it is highly transparent: it explains default section filtering, the effect of include_empty, the meaning of module fields, and that credentials come from MCP headers rather than the caller. It does not claim a read-only flag, but 'Get' plus the absence of any mutation language aligns with a retrieval 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?

Although long, every sentence earns its place: purpose, filtering behavior, output structure, cross-tool routing, and authentication. The main purpose is front-loaded, and the later paragraphs provide necessary detail for a tool with no output schema.

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 completely compensates for the missing output schema by specifying the section and module object shapes, default behavior, and how ids connect to other tools. There are no obvious gaps in what the agent needs to call or interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: course_id is tied to list_courses, and include_empty is explained as showing the 'full week skeleton including blank weeks.' This enriches the schema's terse descriptions without being redundant.

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: 'Get everything the teacher posted in one course', and adds that results are grouped by section/week. It distinguishes itself from sibling tools by asserting a comprehensive week-by-week list of materials, links, forums and assignments, unlike narrower tools like list_assignments or get_announcement.

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 clearly states the input comes from a Moodle course id obtained from list_courses, and it shows how the output ties to other tools (e.g., a forum instance feeds get_announcement). However, it never explicitly states when not to use this tool or names alternative tools for narrower cases.

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, the description carries the behavioral disclosure burden. It explains the exact return structure ({course_id, role, roles}), clarifies that a user can hold multiple roles, and explicitly states that credentials come from MCP settings headers rather than from the agent. This is strong transparency for a simple read-only lookup.

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: it states the purpose first, then role values, then return format, then credential handling. Every sentence adds distinct value with no filler or repetition of schema fields.

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 one-parameter tool with no output schema, the description is complete: it identifies the input source, enumerates expected role values, explains the return fields and their meaning, and clarifies authentication. An agent has enough information to call this tool correctly and interpret the result.

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

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

Schema coverage is 100%, and the schema already documents course_id as a Moodle course id. The description adds useful provenance (from list_courses) and role-value context, but it does not need to compensate for schema gaps. This meets the baseline for a well-covered 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 names a specific verb ('Get'), a concrete resource ('the user's role in one course'), and identifies the required input (Moodle course id). It also distinguishes itself from course listing tools by scoping to a single course and returning role data, not course metadata.

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

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

The description clearly indicates that course_id comes from list_courses, giving an agent a concrete prerequisite and source. It does not explicitly state when not to use the tool or name alternatives, but the narrow scope and role-specific output make the usage context clear.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It specifies the output format (each item fields), explains the meaning of a '-' grade, and clarifies that credentials are taken from MCP settings headers rather than the agent. This gives the agent necessary operational details without stating explicit read-only status, though 'get' implies 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 concise and efficiently structured: the first sentence states the purpose, the second explains the output format, and the third addresses credentials. Every sentence earns its place with no fluff, and the main purpose is 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 simple tool with one parameter and no output schema, the description is complete: it provides the return structure, the meaning of a special grade value, and the credential source. It doesn't mention error cases or pagination, but these are minor for this scope. The agent has everything needed to call it 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?

The schema already describes course_id fully with 100% coverage, including the note 'from list_courses.' The description repeats this same information without adding new semantic meaning about the parameter. Since the schema covers it, the baseline is 3; the description adds no additional parameter-specific insight.

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

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

The description states a clear verb and resource: 'Get the student's own grade items for one course.' It distinguishes itself from siblings by focusing on grades specifically, and it clarifies the input is a Moodle course id from list_courses. This unambiguously differentiates it from course listing, announcements, and assignment 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 a clear prerequisite: the course id must come from list_courses. It implies the tool is for retrieving grades for a single course, but does not explicitly state when not to use it or name alternatives. The context is clear enough for an agent to know this is the go-to for grades, but it lacks explicit 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?

With no annotations provided, the description carries the full disclosure burden and does so thoroughly. It reveals the exact type-dependent return shapes, the always-included common fields, that file downloads must be done via browser, and that credentials come from MCP settings headers rather than from the agent. This goes well beyond a generic 'open an item' statement.

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 long due to necessary type-specific detail, but it is tightly structured with a clear opening sentence, parameter guidance, and a bullet-like breakdown of return shapes. Every sentence adds value, and the most important usage constraint is 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?

There is no output schema and no annotations, yet the description covers the full item-type matrix, common response fields, optional parameter resolution, download limitations, and authentication source. For an agent selecting and invoking this tool, the available context is sufficient to proceed 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 coverage is 100%, so the baseline is 3, but the description adds useful meaning: `cmid` is the id from `/mod/<type>/view.php?id=<cmid>` or `get_course_contents`, and `course_id` can be omitted entirely because it is resolved from `cmid`. This helps an agent construct a valid call with minimal 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 states a specific verb and resource: 'Open ONE item a teacher posted and return its content, given its `cmid`'. It also differentiates itself by explaining the item-type-specific behavior and explicitly routes forum reading to `get_announcement`, so an agent can distinguish it from siblings like `list_courses` or `get_course_contents`.

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: use this tool to open a single course item from a `cmid`, optionally omitting `course_id` because it is resolved from the `cmid`. It points to `get_course_contents` as the source for `cmid` values and suggests `get_announcement` for reading individual forum posts, but it does not explicitly state exhaustive when-not-to-use conditions.

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 behavioral burden. It discloses the return structure (subject, message, posted, read, url), ordering (newest first), the effect of limit, the unread count, and the authentication source (MCP settings headers). This is strong transparency, though it omits edge cases like empty results.

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. It opens with the purpose, then packs essential behavioral details into a few sentences without fluff. 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 one-parameter getter with no output schema, the description covers output structure, ordering, limit behavior, unread count, and authentication. Nothing an agent needs to call it 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?

The input schema covers the only parameter (limit) with a description ('Max notifications to return.'). The tool description adds 'caps the count,' which is essentially a restatement. With 100% schema coverage, the baseline is 3; no significant additional semantics are provided.

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 'Get the student's Moodle notifications' and gives concrete examples (assignment due reminders, grading, forum posts). It distinguishes from siblings like list_announcements and get_grades by referencing the notification bell, 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 clear context for when to use the tool (to fetch the notification bell) but does not explicitly name alternatives or state when not to use it. The scope is clear, but there's no explicit routing guidance beyond the implied distinctness from 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?

With no annotations provided, the description carries the full behavioral burden, and it delivers: it discloses that only headers are returned, that results are newest-first, that course_id scopes vs. aggregates, the exact tile shape, the Taipei timezone format, and that credentials come from MCP settings rather than the agent. This gives the agent a clear model of what the tool does and what it returns.

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 well-organized: it leads with the core purpose and distinction from get_announcement, then covers parameter behavior, return shape, timezone, and authentication. Every sentence adds value with no redundancy or filler.

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

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

Despite having no output schema and no annotations, the description is self-sufficient: it explains what is returned, how pagination works, how course_id scopes the result, what each tile contains, and where credentials come from. An agent can invoke this tool correctly without needing additional 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?

Although the schema already covers 100% of parameters, the description adds meaningful semantics beyond the schema: course_id is said to come from list_courses and omitting it aggregates across current-semester courses, and limit/offset are tied to the newest-first pagination behavior. This enriches the agent's understanding of how to invoke 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 clearly states the tool lists announcement tiles (headers only, no message body) from a course's Announcements forum, using the specific verb 'List' and a well-defined resource. It also distinguishes itself from get_announcement by explicitly directing the agent to call that sibling to read a full announcement, 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 gives explicit guidance on when to use this tool: it is for scanning announcement tiles, and reading a full announcement requires get_announcement using the discussion_id. It also explains the course_id behavior (specific course vs. aggregate across current-semester courses), which tells the agent exactly how to choose parameters.

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

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

With no annotations, the description carries the full burden and discloses substantial behavior: scope precedence rules, defaults (latest semester, student-only), the semantic distinction between DUE and OPEN dates, Taipei timezone handling, exact return fields with status values, sort order, null semantics, and that credentials come from MCP headers. Only pagination/limits and error behavior are unmentioned, which is minor for a read-only list 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 longer than average but every block earns its place: summary line, scope precedence, date semantics, role filtering, output shape, and credential source are all scannable sections. It is front-loaded with the core purpose and would only be trimmed by removing minor redundancy with the schema's own descriptions of sem.

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 7 parameters with no annotations and no output schema, the description is well-near complete: it defines every parameter's semantics, the return shape, timezone and date format, defaults, sort order, and credential source. The notable gap is no mention of result limits or pagination, and no explicit contrast with upcoming_deadlines, but for a list-query tool the coverage is strong.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the due-vs-open semantic split, gives use-case guidance ('compute ranges from today for 'due this week''), clarifies that course_ids come from list_courses and override sem, and explains the rationale behind include_all_role. This elevates it above 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 opening line names a specific verb and resource ('List assignments') and immediately adds the distinguishing payload: due dates and submission status. It differentiates from siblings by scope ('student's courses'), data carried (status), and the closing claim that it is the best way to answer period-based 'due/opened' questions, which separates it from upcoming_deadlines.

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 explicit when-to-use context: scope precedence for course_ids vs sem, a clear 'best way to answer' date-range questions claim, and default student-only behavior with an override flag. It does not explicitly name sibling tools to use instead for other cases, so it falls short of a 5, but the guidance is concrete and actionable.

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 are absent, so the description carries the full burden. It discloses the non-obvious default (latest semester only), the output fields and their types, possible role values, and that credentials are injected from MCP settings. This is rich behavioral context beyond the schema.

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

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

The description is well-organized: a one-sentence purpose, a compact behavior paragraph, a bulleted output definition, and a short credential note. No sentence is redundant or wasted.

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

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

For a one-parameter list tool with no output schema, the description fully covers return values, default semantics, parameter usage, and authentication behavior. Potential gaps like pagination or error handling are minor and do not prevent correct invocation.

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

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

Although schema description coverage is 100%, the description adds meaning beyond the schema by explaining the default behavior when sem is omitted, the semantic value 'all', and providing example term codes. This gives an agent everything needed to use the parameter 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 states a specific verb ('List'), a precise resource ('the student's enrolled Moodle courses'), and the scope (with role, filtered by semester). It clearly distinguishes this from sibling search_courses by limiting to enrolled courses.

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

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

The description explicitly explains the default behavior (latest semester only) and how to use the sem parameter for a specific term or 'all'. It does not name alternative tools directly, but the enrollment scope and parameter guidance give a clear usage 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?

No annotations are provided, so the description carries the full burden — and it delivers. It discloses case-insensitive substring matching, the matchable name fields with examples, the default all-terms scope, sem scoping semantics, return field list, newest-term-first ordering, empty-query behavior, and the fact that credentials come from MCP settings headers rather than the agent. This is unusually complete behavioral disclosure for a tool with zero 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 slightly longer than the calibration ideal, but every sentence earns its place — purpose, matching details, scope behavior, return format, and credential note are each useful. It is front-loaded with the core purpose. A minor deduction for some redundancy between the schema and description (sem values are restated), though the description does add interpretive 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?

For a 2-parameter search tool with no output schema, this is near-complete: it covers what is matched, how it is matched, default and scoped behavior, return fields, and ordering. The only gap is the absence of explicit pagination or result-limit information, which is minor given the tool mirrors list_courses behavior. An agent has everything it needs to invoke this 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 coverage is 100%, yet the description still adds substantial meaning beyond the schema. It explains what 'all' means as a default scope, how sem values map to behavior (term code vs 'latest'), and gives concrete example queries ('物件導向', 'Object-oriented', '703009'). The schema only labels parameters; the description supplies the matching and scoping semantics.

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

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

States a specific verb-resource pair (search enrolled courses by keyword) and anchors it to a concrete analog (the Moodle app's filter box). It explicitly names the matching semantics and the three name components (NCCU term code, Chinese title, English title), which makes the tool's purpose unmistakable. It also differentiates from the sibling list_courses by describing the empty-query equivalence.

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?

Clearly describes when this tool is appropriate: keyword search across all enrolled courses or scoped to a term via the sem parameter. It references list_courses twice ('same fields as', 'same as list_courses'), which implicitly routes the agent to the list-all alternative, and explains the default all-terms behavior. It stops short of an explicit 'use list_courses when you want everything unfiltered' exclusion, hence 4 rather than 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?

With no annotations, the description carries full burden and it does a thorough job: it discloses the default 14-day window, the role-filter semantics, that personal/site events are always kept, the exact return fields, the timezone (Taipei time), the sort order (soonest first), and that credentials come from MCP settings rather than from the agent. This level of behavioral detail is rare and clearly exceeds what a simple 'list' description would 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 purpose in the first sentence, then layers role-filtering, output format, and credentials in a logical sequence. Every sentence contributes a distinct fact; there is no filler or repetition. It is longer than a typical tool description but justified by the density of useful information (timezone, sort, fields).

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

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

There is no output schema, so the description must explain the return format itself—it does, listing all fields and their meaning (due in Taipei time). It also covers sorting, default filtering, and authentication source. For a read-only 'list' tool this is complete; an agent could call it correctly without needing to guess any behavior.

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

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

Schema coverage is 100% (both parameters are described), so the baseline is 3. The description adds value beyond the schema by explaining the semantic difference of include_all_role (including teacher/TA courses) and reiterating the default for days. It also mentions the role field in the output, which indirectly clarifies what the parameter means for the response. This moves it above the schema-only 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 opens with a specific verb-resource pair ('List the student's upcoming action events') and scopes it precisely (across courses, within a time window). It also asserts 'This is the best what's due soon overview,' which signals its intended niche relative to the sibling tools (list_assignments, get_notifications, etc.), so an agent can distinguish it without opening their schemas.

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 clearly explains when to use it ('best what's due soon overview') and how the role filter changes the result set ('By default only events from courses where you are a STUDENT... set include_all_role true to also include teacher/TA courses'). It does not explicitly name alternatives or state when NOT to use it, but the purpose is clear enough that an agent can reasonably choose it over siblings that list specific resource types.

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