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

The annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds genuinely non-obvious behavioral context beyond them: data tools authenticate automatically, and a false status does not imply that manual login is needed. That is exactly the kind of semantic guidance structured fields cannot carry.

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

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

Three sentences, front-loaded with the purpose and then the usage constraints. Every sentence earns its place, and the counter-intuitive warning is placed last but clearly scoped.

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

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

For a zero-parameter status probe with no output schema, the description covers what the tool does, when to invoke it, when not to, and how to interpret a negative result. No important invocation 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?

The tool takes zero parameters, so there is nothing to document and the baseline is a 4. The description correctly avoids inventing parameter behavior, though it also does not describe what the returned status values look like.

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 precise verb and resource: reports whether the current MCP process has an authenticated LearnUs session. It also distinguishes itself from the sibling data tools by clarifying that it is a status check, not a data accessor.

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?

Explicitly scopes usage to the case where the user directly asks about login/session state, and explicitly forbids using it as a prerequisite for data calls. It also preempts a likely misinterpretation (that a false status requires manual browser login).

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?

Adds real context beyond annotations: it explains why readOnlyHint=false (it creates a local file) while clarifying that remote LearnUs data is not modified, and it discloses no-overwrite semantics, which a caller cannot infer from the schema. It stops short of covering auth prerequisites and rate/error behavior, so it is strong but not exhaustive.

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?

Front-loaded with the action and scope, then layered guidance (preference, side effects, input constraint, fallback) in discrete sentences. Slightly long at six sentences, but each one carries a distinct rule rather than restating structured 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 single-parameter tool with no output schema, the description covers purpose, preconditions, side effects, input constraints and fallback routing. Everything an agent needs to invoke it correctly and to know its limits is present.

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 already 100% and the fileId description names the producing tools, so the baseline is 3. The description goes further by constraining acceptable input ('Do not pass URLs or guessed IDs'), which prevents a common misuse the schema alone does not forbid.

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 (downloads) and resource (a previously discovered LearnUs fileId into the configured local directory), which cleanly distinguishes it from retrieval siblings like learnus_list_files. An agent can tell immediately that this is the local-materialization tool rather than a metadata reader.

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?

Explicit when-to-use ('Use only when the user explicitly asks to download that file'), an explicit alternative ('Prefer this Tool over browser download'), and an explicit condition for the fallback ('only when MCP reports the file/capability unsupported or explicit visual interaction is required'). Both the preferred tool and the excluded path are named.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds value: it discloses that attachments get registered as fileIds, a side effect not captured by any annotation. It doesn't describe error behavior or what 'normalized' entails, keeping it short of a 5.

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

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

Three compact sentences, front-loaded with the operation and its side effect, then usage scope, then exclusions. No filler and every clause carries routing 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 two-parameter read tool this is complete: purpose, identification source, side effect, and negative scope are all stated. No output schema exists, but the description already indicates what is returned ('normalized announcement body') and the attachment registration.

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

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

Schema description coverage is 100% and both required params are documented there, including that the IDs come from learnus_list_announcements. The description only restates that the announcement is identified by moduleId and articleId, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Gets'), resource ('one normalized LearnUs announcement body'), and an additional effect ('registers its attachments as fileIds'). It explicitly distinguishes itself from list/search siblings and from mark-read behavior, so an agent can route to it without opening the schema.

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?

Gives an explicit positive condition ('when the user asks to read a specific announcement already identified by moduleId and articleId') and explicit exclusions ('Do not use it to list or search announcements, or to mark a notice read'). Alternatives are named by function, leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds useful context by enumerating the returned content (instructions, due date, attachments, submission/grading status), which is meaningful given there is no output schema; it stops short of noting auth or pagination behavior.

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

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

Three compact sentences, front-loaded with what the tool returns before the usage and anti-usage clauses. Every sentence carries a distinct instruction with no repetition.

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?

Single required parameter, full schema coverage, rich annotations, and the description compensates for the absent output schema by naming what is returned. Nothing needed 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?

Schema coverage is 100% and the cmid parameter is fully documented in the schema, including where it comes from. The description only echoes 'canonical activity cmid', adding no syntax or format detail beyond the structured field, so baseline 3 applies.

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

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

States a specific verb (gets one assignment) plus the scope of returned data (instructions, due date, attachments, submission/grading status) and the lookup key (canonical activity cmid). An agent can distinguish it from list/search siblings without opening the schema.

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?

Gives an explicit trigger (user asks for details or status of a specific known assignment) and explicit exclusions (not for searching across courses, not for submitting/editing). This leaves nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds only that the output is a 'normalized structure and activities', which hints at the response shape but does not cover pagination, result size, or what 'normalized' means. With annotations carrying the burden, this is adequate but not rich.

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

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

Three short sentences: purpose first, then positive usage trigger, then negative exclusions. Every sentence earns its place with no redundancy.

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

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

Single required parameter, no nested objects, no output schema, and the description signals the return contents ('normalized structure and activities'). Nothing essential is missing for correct invocation, though the absence of an output schema leaves the exact return shape underspecified.

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's own description explains courseId must be an exact Moodle course ID from a LearnUs course tool. The description's phrase 'one known LearnUs course' reinforces this but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Gets) and resource (one known LearnUs course) plus the returned scope (normalized structure and activities). It is immediately distinguishable from learnus_list_courses, which is the sibling covering discovery of many 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?

Gives an explicit trigger condition ('when an exact course is known and the user asks for that course's contents or structure') and explicit exclusions ('Do not use it to discover all enrolled courses or to fetch full assignment/announcement details'), routing the agent to learnus_list_courses, learnus_get_assignment, and learnus_get_announcement.

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 this read-only, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real value beyond them by disclosing the epistemic distinction between confirmed required/optional items and 'unknown' states, warning the agent not to overstate certainty. It does not mention caching behavior (left to the refresh param).

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

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

Two sentences, both earning their place: the first front-loads what is summarized, the second front-loads the trigger and the exclusions. No filler or repetition 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?

With no output schema, the description usefully enumerates the reported categories (required incomplete, completed, optional/excluded, unknown), which is what an agent needs to interpret results. It stops short of describing aggregation level (per week vs per course) or return shape, a minor gap for a summary 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 100% (week, status enum, refresh, courseId all documented in-schema), so the baseline is 3. The description adds no parameter-level detail such as the week/courseId relationship or when to set refresh, so it does not exceed 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?

States a specific verb (summarizes) and resource (VOD learning states across a course/week), and enumerates the state categories it reports. However, it never distinguishes itself from the very close sibling learnus_get_video_attendance, which the 'attendance' phrasing overlaps with, so an agent must infer the boundary from the schema.

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?

Gives an explicit when-to-use trigger ('user asks about course video learning, completion or attendance across a course or week') and two when-not conditions (non-video coursework; treating unknown targets/deadlines as confirmed obligations). The alternative tool is not named, and the second exclusion is phrased cryptically, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds non-obvious semantics: it is configurable/broad by default, and that 'informational, completed and unknown items remain distinct' — a result-shaping trait not implied by annotations or schema. It stops short of describing pagination or section defaults.

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

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

Three tightly packed sentences, front-loaded with the core purpose before routing advice. Every sentence carries routing or behavioral information; the closing sentence on item-state distinction is terse but purposeful. Slightly dense but no waste.

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 10-parameter, zero-required aggregator with no output schema and full annotation coverage, the description supplies the missing decision layer — when to pick it over siblings and what conceptual sections exist. Range defaults and section limits are left to the schema, which is reasonable.

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 10 parameters including the date formats, courseId provenance and include* defaults. The description only implicitly maps its category list to the include flags, adding little beyond the schema. Baseline 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?

States a specific verb and resource: 'Gets a configurable broad LearnUs coursework summary' with an explicit enumeration of what it spans (assignments, calendar deadlines, announcements, notifications, optional learning/attendance). An agent can tell this apart from narrower siblings like learnus_upcoming or learnus_get_weekly_tasks without opening the schema.

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?

Gives explicit when-to-use ('default broad LearnUs retrieval Tool when a request spans multiple categories or the exact underlying resource is not yet known'), explicit when-not-to-use ('generic personal to-do/calendar questions', 'focused request that maps cleanly to a narrower Tool'), and names the concrete alternative for weekly tasks (learnus_get_weekly_tasks). Full 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the useful nuance that returned attendance is 'canonical' rather than inferred from titles, but says nothing about freshness/caching behavior (despite the refresh param) or failure modes for unknown IDs.

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

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

Three tight sentences, front-loaded with what is returned, then when to use it, then what it is not for. No filler or redundancy.

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

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

Without an output schema, the description usefully enumerates the returned concepts (completion, viewing progress, attendance target, attendance status) and covers all three parameters indirectly. It could say a bit more about error behavior for an unknown videoId, but it is adequate for calling 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 courseId, videoId and refresh are already fully documented in the schema, including the 'omit to return the course report' behavior. The description's phrase 'for a course or one known video' merely restates what the schema already conveys, so baseline 3 applies.

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

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

States a specific verb+resource ('Gets canonical completion, viewing progress, attendance target and attendance status') with a precise scope ('for a course or one known video'). It is easily distinguishable from siblings like learnus_list_videos, which enumerates videos rather than reporting attendance for one.

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?

Gives a clear triggering condition ('Use when the user asks whether a specific course video was watched, completed or counted for attendance') plus two explicit exclusions (not for playing a video, not for inferring attendance from a title). It stops short of naming an alternative sibling tool to route to, so it falls just under the top band.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it filters out informational/completed/optional/unknown items and warns that calendar entries alone do not prove an unfinished task, which shapes how results should be interpreted.

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?

Front-loads the core purpose before the guidance, and each sentence carries usable information. It runs long (five sentences) with some repetition across the trigger/exclusion clauses, but no sentence is pure filler.

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

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

For a read-only, idempotent query tool with 100% schema coverage, no output schema, and no required parameters, the description covers purpose, invocation triggers, exclusions, and result-interpretation caveats. Nothing an agent needs to select or 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?

Schema description coverage is 100%, with 'from', 'to', and 'courseId' fully documented including Asia/Seoul date semantics and Moodle course ID lookup. The description adds nothing about parameter syntax or defaults, so the baseline 3 applies.

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

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

States a specific verb and resource ('gets actionable Yonsei LearnUs coursework') with clear scope (current or requested week) and enumerates the item types returned (assignments, deadlines, incomplete learning, attendance). No sibling is named explicitly, so differentiation from overlapping tools like learnus_upcoming or learnus_get_learning_overview is inferred rather than stated.

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?

Explicitly designates itself as the default LearnUs tool, gives a positive trigger condition (coursework/classes/assignments/deadlines even without the keyword LearnUs), and states a negative exclusion (unrelated personal to-do/calendar questions, or treating informational/completed/optional/unknown items as required). This is near-ideal when-to-use/when-not 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 readOnly/idempotent/non-destructive/openWorld, so the safety bar is low. The description still adds two behavioral traits beyond them: the listing surfaces 'unknown activity types' (so results may include unclassified entries) and it can reveal cmids, which explains why it is a lookup entry point. It omits pagination or result-size behavior, so it is not perfect.

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

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

Three sentences, front-loaded with the capability, followed by use conditions and exclusions. Every sentence carries distinct 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 read-only single-parameter listing tool with no output schema, the description covers what is returned (the activity type set), when to call it, and what it is not for; annotations cover the safety profile. An agent has everything needed to invoke 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?

Schema coverage is 100% for the single courseId parameter, whose description already specifies it is an exact Moodle course ID from a LearnUs course tool. The description only implies scoping to 'one course' and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The description names a specific verb (Lists) and enumerates the exact resource set (assignments, VODs, resources, folders, boards, unknown activity types) scoped to one course. It is clearly distinguishable from siblings like learnus_get_assignment (details) and learnus_get_learning_overview (cross-course summaries).

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

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

It gives explicit triggering conditions (user asks what activities/materials exist in a known course; a cmid must be discovered) and explicit exclusions (full activity details, cross-course summaries), naming the class of alternatives to prefer instead. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds behavioral value beyond the annotations: results are normalized summaries, returned newest-first, and are intentionally not full bodies. It stops short of any pagination or rate-limit detail, so not a 5.

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

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

Three sentences, no filler, and the ordering/scope constraint is front-loaded before the usage and exclusion guidance. Every sentence carries information the agent needs.

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 two-parameter read-only list tool with no output schema, the description covers scope, ordering, return granularity (summaries, not bodies) and the routing alternative. It could say slightly more about what fields a summary contains, but nothing needed for correct invocation 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 100%, so both parameters (limit default 10/max 50, courseId pattern) are already documented. The description only restates the optional single-course filter ('optionally in one known course') and implies newest-first ordering from limit, adding little beyond the schema. Baseline 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?

States a specific verb (Lists), resource (normalized LearnUs ubboard announcement summaries), and scope/ordering (newest dated items first). The sibling it must not be confused with, learnus_get_announcement, is named explicitly.

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?

Gives a positive trigger ('recent course notices or announcements, optionally in one known course') and an explicit exclusion ('Do not use it for a full announcement body') with the correct alternative tool and the condition (known module/article IDs) that selects it.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description still adds behavioral value by disclosing what the call yields (current courses plus canonical Moodle IDs that other tools consume), though it omits pagination, auth, and result ordering 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?

Three short sentences with the capability front-loaded, followed by usage and exclusion; every clause carries information and nothing is repeated from annotations or 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?

For a zero-parameter list tool with no output schema, the description covers what is returned (courses and canonical IDs), when to call it, and when not to, which is everything an agent needs to invoke 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 tool takes zero parameters, so the baseline of 4 applies; the description correctly implies the call is unfiltered and scoped to 'the user's current' courses, so no parameter gaps exist.

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 ('Lists the user's current LearnUs courses') and adds a distinguishing scope detail ('canonical Moodle course IDs') that separates it from the several other list_* siblings. An agent can identify what this returns without opening any schema.

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?

Gives explicit when-to-use conditions (user asks which courses they take, or another LearnUs tool needs an exact course ID) and an explicit when-not ('Do not use it for activity, assignment or file details inside a known course'), effectively routing to list_activities, get_assignment and list_files.

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 readOnly, idempotent, non-destructive and openWorld behavior. The description adds useful context beyond them: results are pre-filtered to 'safe downloadable' items, and the identifiers returned are opaque fileIds suitable for a later download call. It does not describe cache scope or any cap on results, keeping it short of a 5.

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?

Front-loaded with the core purpose, then usage triggers, then exclusions. No filler sentences, though the second sentence packs three triggers and two prohibitions densely.

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

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

With no output schema, the description correctly volunteers what comes back (fileIds plus completion state). Combined with full schema coverage and rich annotations, an agent has enough to call it correctly; only result limits and the exact definition of 'safe' remain unspecified.

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% (scope, refresh, courseId are all documented, including the enum meaning), so the schema carries parameter meaning. The description adds no syntax or format detail beyond it; per the baseline rule, 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?

States a specific verb (Discovers) and resource (course materials, PDFs, attachments) and clarifies the return shape (opaque fileIds plus Moodle completion state). This cleanly separates it from learnus_download_file, which retrieves content rather than enumerating it.

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?

Explicitly names the trigger (user asks for course files, lecture materials, PDFs, attachments, downloads) and two exclusions (downloading arbitrary URLs; assuming a file still needs review). Both when-to-use and when-not-to-use are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description still adds real value beyond them: it guarantees the read does not mark notifications as read (a side-effect that readOnlyHint alone would not clarify) and warns that notifications are informational, not implicit task assignments.

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

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

Two tight sentences with zero filler; the core action and its side-effect guarantee are front-loaded before the usage and exclusion clauses. Every clause carries distinct 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 one-parameter, no-output-schema list tool with full annotation coverage, the description covers purpose, trigger, exclusion and side effects adequately. The only gap is that 'normalized' notifications are not characterized (what fields come back), which matters slightly given there is no 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 100%, and the single 'limit' parameter already documents its meaning, default and bounds. The description adds no additional semantics about ordering or the meaning of the limit, so baseline 3 applies.

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

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

States a specific verb and resource ('Lists normalized LearnUs account notifications') plus a key side-effect constraint ('without marking them read'). The resource is distinct from the sibling announcement tools, though the description never explicitly contrasts itself with learnus_list_announcements, so the sibling differentiation is implicit rather than stated.

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?

Gives an explicit trigger ('Use when the user asks about recent LearnUs alerts or notifications') and an explicit exclusion ('Do not use it to infer a required task merely from a new-file notice'). No alternative sibling tool is named for the excluded case, so it stops short of full when/when-not/alternative 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 readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral value beyond them: it names the returned fields (canonical IDs, audience applicability, dual deadlines) and explicitly disclaims attendance/progress semantics, though it says nothing about the refresh cache behavior or rate limits.

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

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

Three short sentences, zero filler, with the core purpose front-loaded and the exclusion last. Every clause carries either scope, trigger, or routing 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?

With no output schema, the description compensates by naming the returned content, and it covers trigger, scope, and the nearest confusable sibling. Nothing material for correct invocation 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 100%, so both parameters (courseId, refresh) are already documented in the schema. The description's 'in one course' reinforces courseId scoping but adds no format, ID-source, or refresh guidance beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (Lists) and resource (VOD activities in one course) and enumerates the distinguishing payload (canonical IDs, audience applicability, separate availability/instructional deadlines). An agent can separate it from learnus_list_activities and learnus_list_files without opening any schema.

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?

Gives an explicit trigger ('user asks what course videos exist or for video metadata in a known course') plus a when-not with two named alternatives (learnus_get_video_attendance, learnus_get_learning_overview). Nothing about tool selection is left to inference.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: 'canonical' events (implying deduplicated/authoritative source), the date-only Asia/Seoul default, and that timestamps require a timezone. It doesn't disclose return shape or the limit/pagination behavior, keeping it short of a 5.

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?

Four short sentences, front-loaded with purpose then trigger then exclusion then timezone caveat. Slightly redundant since the timezone rule is also encoded in the schema, but every sentence is otherwise doing work.

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

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

With 4 fully documented params, no nested objects and no output schema, the description covers what an agent needs to select and call the tool: scope, filtering by course, timezone handling, and the sibling to prefer for tasks. Return format is not specified, but with no output schema that 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 100%, and each of the four params is documented in-schema, so the baseline is 3. The description's timezone sentence largely restates what the from/to schema descriptions already say, adding little parameter-level meaning of its own.

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 (Lists), resource (canonical LearnUs calendar events and deadlines), scope (date range, optionally one course). It names the sibling it is not (learnus_get_weekly_tasks), so an agent can distinguish it without opening any schema.

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?

Gives an explicit trigger ('user asks for calendar events, schedules or deadlines between specific dates'), an explicit exclusion ('do not use it to infer task completion or required attendance'), and names the correct alternative for that case. Nothing is left to inference.

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