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

readOnlyHint=true already covers the safety profile, so the description's added value is its disclosure of mode-dependent output (Lesson list/progress, lesson body, or quiz content), which is meaningful because there is no output schema. It does not detail pagination or the offset/max_chars return behavior, keeping it just short of full transparency.

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

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

Three compact sentences, zero filler. Purpose and modes come first, alternatives second, return value last – well front-loaded and each sentence earns its place.

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

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

With no output schema, the description usefully covers return values and routes to siblings, which is sufficient for a mode-switching read tool. Minor gaps remain around pagination behavior across the offset/max_chars parameters, but the schema documents those.

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

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

Schema description coverage is 100%, so the baseline is 3. The description gestures at the mode switching (list/lesson/quiz) but the concrete semantics (quiz=true returns quiz, lesson with a value reads the body) are already spelled out in the schema, so the description adds little beyond what structured fields provide.

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 (读取 Ed Lessons) and enumerates its three modes: list progress, read a single lesson, or read a quiz. It explicitly names the sibling tools it is not (search_ed_threads for discussions, search_content for full-text search), 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?

Names two alternatives with the exact condition that selects each: use search_ed_threads for Ed discussions and search_content for cross-courseware full-text search. This is explicit when-to-use-else guidance, not implied.

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 readOnlyHint=true already covering the safety profile, the description adds that the tool returns either a status summary or a full checkup ('返回状态摘要或完整体检'), which tells the agent what output to expect. It doesn't describe auth requirements or rate limits, but for a read-only diagnostic tool this addition is meaningful beyond the annotation.

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

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

The description is front-loaded with the tool's purpose, then usage guidance, then alternatives, in three tight sentences with no wasted words. Every sentence earns its place by either defining scope or routing to siblings.

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 diagnostic tool with one optional boolean parameter and no output schema, the description covers purpose, usage, alternatives, and expected return format. Annotations handle safety, and 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?

Schema description coverage is 100%, and the single parameter's meaning ('true=完整诊断；false=简要状态') is fully captured in the schema itself. The description's mention of '状态摘要或完整体检' maps to the same boolean but adds no syntax or format detail beyond what the schema already provides, 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 clearly states the verb 'diagnose' and lists specific resources: login, sync, indexing, and error status. It explicitly distinguishes itself from sibling tools by naming sync_monash_data and start_monash_login with their appropriate use cases, so an agent can tell them apart without opening 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 gives explicit when-to-use guidance ('报错或“用不了”时用') and names two alternative tools with the conditions that select them ('只需刷新数据用 sync_monash_data'; '登录过期且用户同意后用 start_monash_login'). This is exactly the kind of when/when-not/alternatives routing that usage guidelines require.

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 safe-read profile is covered. The description adds value beyond that by disclosing the output-shaping behavior (overview vs. detailed grade items/feedback), though it says nothing about permissions, pagination, or caching.

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?

Compact single statement, front-loaded with the purpose, then the conditional output, then the boundary cases. Every clause earns its place 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?

With no output schema, the description carries the return-value burden and does so, explaining that callers get an overview or grade items/scores/feedback depending on the course param. Sufficient for a two-parameter read 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%, so both parameters are already documented in the schema. The description reinforces the course/no-course branch but adds no format or constraint detail beyond what structured data provides, making the baseline 3 correct.

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?

Specific verb+resource ('读取 Moodle 成绩') and it distinguishes itself from siblings by naming list_moodle_assignments and the due-date calendar explicitly. An agent can tell this apart from list_moodle_assignments/list_moodle_due 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?

Explicit when-to-use routing: with no course param it returns an overview, with course it returns grade items/scores/feedback. It also names the correct alternative for submission status and states what it is NOT for (deadlines). 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?

With readOnlyHint=true already declared, the description adds valuable context beyond annotations: that reading messages does not mark them as read, and that it returns conversations or messages depending on the input. It does not cover permissions, rate limits, or pagination, but the added behavioral detail is meaningful.

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 very concise and front-loaded, starting immediately with the core purpose. Every sentence carries useful information, and there is no redundant or filler text.

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

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

Given the simple two-parameter tool, no output schema, and existing readOnly annotation, the description covers all an agent needs: what it does, how the parameters affect behavior, when to use an alternative (forum), and what it returns. Nothing essential 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 the parameter meanings are already fully documented in the schema. The description reiterates the conversation_id behavior (without it lists conversations, with it reads that conversation) but adds no new semantic details such as formats, constraints, or edge cases.

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 (读取/read) and resource (Moodle 私信/private messages), and explicitly distinguishes from the sibling search_moodle_forum by saying forum content should use that tool instead. It also clarifies the conditional behavior based on conversation_id, making the tool's scope unambiguous.

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

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

It provides an explicit alternative for forum content (search_moodle_forum), which is the most likely source of confusion among siblings. However, it does not explicitly state when to use this tool versus other non-forum Moodle tools, nor does it mention prerequisites or exclusions beyond the forum case.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds genuine context beyond that: it discloses the aggregation scope across multiple sources and that output is categorized ('返回分类待办'). No auth/pagination behavior is described, but for a read-only reader this is adequate.

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 clauses: purpose/scope, trigger context, and sibling routing. Zero filler and the aggregation scope is front-loaded before the alternatives.

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?

Complete for a read-only aggregator: purpose, when-to-use, alternatives, and return shape ('返回分类待办') are all present, and annotations handle safety with no output schema needed. Minor gap is the absence of any note on result volume or freshness, but nothing essential 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 single 'days' parameter is fully documented in the schema (未来天数, 默认7). The description adds no syntax or format details beyond that, so baseline 3 applies as the schema does the heavy lifting.

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

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

States a specific verb+resource (综合查看 Moodle/Ed 待办) and explicitly enumerates what it aggregates: deadlines, missed submissions, Lessons, announcements, unread replies. It also names the sibling tools it is not (list_moodle_due, list_moodle_assignments), so an agent can distinguish it without opening 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?

Gives explicit trigger context ('问"这周要做/交什么"用') and clear when-not routing: deadlines only → list_moodle_due, submission status → list_moodle_assignments. Alternative selection is fully specified rather than inferred.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower; the description still adds real behavior by disclosing the fallback to the local course table when Moodle is not logged in. It does not describe pagination or result size limits, but the fallback note is substantive context beyond the annotation.

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

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

Front-loaded with the verb and resource, then two short qualifiers (when to use it, fallback behavior) and the return fields. Every clause carries information and nothing is repeated from structured data.

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 fields (course code, name, identifier), and it covers the login-state edge case. For a zero-parameter listing tool that is complete enough to call 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 there is nothing for the description to disambiguate; baseline 4 applies. The description correctly does not invent parameter guidance.

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 (列出课程/list courses) and names both data sources (Moodle/Ed). It also positions itself as the course-discovery hub that other tools depend on, which distinguishes it from the content-specific siblings like get_moodle_grades or list_moodle_due.

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 two concrete use conditions: when the user asks what courses exist, and when another tool first needs to resolve a course. No explicit when-not or named alternative is provided, but the triggering contexts are 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that: it discloses the return shape (更新分组 and 同步时间) and, via the personal-scope wording plus the peek cursor semantics, signals that this is a cursor-advancing personal feed. That is meaningful context on top of the annotation.

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

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

Three tightly packed clauses that are front-loaded: what it lists, then the sibling routing, then the return shape. No wasted words, though the sibling routing could be trimmed slightly.

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 list tool it is essentially complete: annotations carry the safety profile, all params are schema-documented, and the description even states the return structure (groups + sync time) despite no output schema. Nothing critical 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 all four parameters (peek, limit, since, course) are already documented in the schema, including the cursor behavior of peek. The description adds no syntax or format detail beyond the schema, so the 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 (列/list) and resource (Ed 新帖、新回复、本人相关未读回复), and explicitly contrasts with the two sibling tools search_ed_threads and read_ed_thread. An agent can distinguish this from its siblings without opening either 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?

Explicitly routes the agent: browse/search historical posts → search_ed_threads, read a full post → read_ed_thread, while this tool surfaces fresh updates. The when-to-use and alternatives are named directly rather than implied.

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 only readOnlyHint=true in annotations, the description adds genuine context beyond structured data: it discloses the return content (files/links) and that returned paths are consumable by read_file, enabling chaining. It stops short of pagination or ordering behavior, 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 tight clauses, front-loaded with the primary action and immediately followed by exclusions and alternatives. No filler sentences; every clause carries routing or return-value 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?

No output schema exists, and the description compensates by stating the return contents and the downstream usability of paths. That is sufficient for a read-only list tool, though result ordering or filtering interactions between week/links/query are left unaddressed.

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 week, links, query and course. The description only implies the links scope (列外链) without adding format or default semantics 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?

States a specific verb (列/list) and resource (已同步本地课件或外链), and explicitly scopes it as not searching content. It draws clear boundaries against the siblings search_content and read_file, so an agent can route 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 negative guidance (不搜索正文) plus named alternatives with their selecting conditions: search_content for full-text, read_file for reading a path. This is exactly the when/when-not/alternatives pattern.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the scope of returned data (deadline, submission, grade status) and the meaning of missing_only, but says nothing about pagination, result volume, or whether course omission aggregates across all courses beyond the schema's '省略=全部'.

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?

One dense sentence that front-loads purpose, then routes to the two alternatives, then notes the key filter mode. No filler and no repetition of the tool name or title.

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-optional-parameter, read-only list tool with no output schema, the description covers purpose, alternatives, and the main filter well. Minor gap: no mention of result shape or multi-course aggregation behavior, but nothing blocking 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?

Schema description coverage is 100%, so both parameters are already documented (course format example, missing_only semantics). The description only restates the missing_only behavior, adding no new format or value 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 (列/list) and resource (Moodle 作业) plus the exact scope it covers: 截止、提交和可用成绩状态. It also names the two sibling tools it is not, so an agent can route 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?

Explicitly gives when-to-use-this vs alternatives: use list_moodle_due for calendar deadlines only, get_moodle_grades for grades/feedback only. It even flags the missing_only filter as a conditional usage mode.

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 already marks it as a safe read. The description adds meaningful behavior beyond annotations: it discloses the iCal fallback when not logged in and says it returns deadline events and times. It does not cover rate limits or pagination, but those are minor here.

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: purpose first, sibling alternatives next, fallback and return content last. Every clause carries useful selection or behavior 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-only list tool with no output schema, the description is nearly complete: it states scope, alternatives, auth fallback, and return content. Only minor details such as exact event ordering or timezone handling are absent.

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 days and course are already documented in the schema. The description does not add parameter syntax or constraints beyond the schema, so it meets the baseline 3.

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 gives a specific verb+resource: listing Moodle future deadlines and calendar events. It explicitly distinguishes the tool from list_moodle_assignments and get_moodle_grades, so an agent can select it without opening sibling 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 states when to use this tool (upcoming deadlines/calendar events) and names the correct alternatives for submission status/assignment details and grades. It also gives a fallback condition for unauthenticated use, leaving little 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 only declare readOnlyHint=true, so the description carries the rest: it discloses the return format (Markdown), that long content is paginated, and that live=true triggers a real-time refresh from Ed. It does not cover auth requirements or error behavior, but the read-only safety profile plus format/pagination disclosure is solid added value.

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?

A single compact sentence with the core action front-loaded, followed by sibling routing and the live flag, then return format. No redundant or filler text.

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

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

For a read tool with no output schema, the description supplies the essential missing pieces: output format (Markdown), pagination support, refresh semantics, and sibling alternatives. Remaining gaps (auth prerequisites, error cases) are minor for a read-only thread fetch.

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 all four parameters (thread, live, offset, max_chars) are already documented in the schema. The description only reinforces pagination and live refresh at a high level, adding little syntax or constraint detail beyond what the schema provides. 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: read a single Ed thread's body and replies. It explicitly distinguishes itself from the two nearest siblings (search_ed_threads for finding, list_ed_updates for new activity), so an agent can pick 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 explicit routing: use search_ed_threads to locate a thread and list_ed_updates for new activity, implying this tool is for fetching a thread you already have an identifier for. It also states the live=true precondition for refreshing before reading.

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?

readOnlyHint=true already declares the safety profile, so the description's job is to add context, which it does: ZIP archives are traversed via `inner`, long payloads are paginated with offset/max_chars, and the return is text or a ZIP listing. It stops short of error behavior (missing path, oversized file, encoding), but the added behavioral detail exceeds the annotation.

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

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

Three compact clauses, front-loaded with the primary action and dependency, then the ZIP and pagination conditions, then the fallback search guidance. Every sentence carries distinct operational information with zero padding.

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 readOnlyHint covering safety and a 100%-documented schema, the description closes the remaining gaps by stating the return shape (text or ZIP listing) and the pagination model, which matters since no output schema exists. Only minor error/edge-case behavior is absent.

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 use-case meaning: `inner` is the ZIP-internal selector (omitted = list the ZIP) and offset/max_chars are the pagination pair for long content. That is modest but genuine value beyond the raw schema strings.

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 (读取/read) and resource (课件路径/course material file), and pins the scope to paths produced by list_files/search_content, distinguishing it from those siblings. An agent can tell this is the terminal read step in the list/search -> read workflow 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?

Explicitly routes the agent: paths come from list_files/search_content, and if the target file is unknown, use search_content first. This is a named alternative plus the condition that selects it, 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 only declare readOnlyHint=true, so the description carries the rest; it discloses the return shape (matching snippets, file paths, and location info), which is valuable since no output schema exists. It stops short of pagination/limit behavior or scope limits beyond the sibling routing, 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?

Single dense sentence, front-loaded with the core purpose and return values, followed by sibling routing. Every clause earns its place with 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?

Covers purpose, alternative selection, and return content in one line for a read-only search tool whose annotations already carry the safety profile. An 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?

Schema coverage is 100%, so all three params (query, limit, course) are already documented in the schema. The description adds no syntax or format detail 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 (全文搜索/full-text search) and precise resource scope (已同步课件/PDF/笔记/字幕), and explicitly names the sibling tools it is not (list_files, read_file). An agent can distinguish this from every sibling without opening a 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-alternative routing: use list_files to merely enumerate files, and read_file once a path is obtained. This establishes a clear workflow and names the conditions that select each alternative.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds behavior beyond that: the tool returns post summaries (not full bodies) and browse mode supports offset pagination, which is genuinely useful call-shaping 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?

Two tight sentences, front-loaded with the core verb+resource, followed by the routing alternatives and return/pagination note. 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?

With no output schema, the description still tells the agent the return shape ('post summaries') and the pagination mode, and it points to siblings for full content. Complete enough for a read-only search tool, though return fields and summary limits are only roughly characterized.

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% — every one of the 9 parameters is already documented with enums, defaults and limits. The description only echoes the offset/pagination behavior, which the schema already notes as ignored during search. 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 (browse/search) and resource (Ed posts), and explicitly distinguishes itself from two siblings — read_ed_thread for full body/replies and list_ed_updates for new activity. An agent can route among the three 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?

Names both alternatives with the exact condition that selects each: full content -> read_ed_thread, new activity only -> list_ed_updates. This is explicit when-to-use/when-not guidance, not inferred 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?

The readOnlyHint annotation already covers the safety profile. The description adds return behavior: announcements or matching post summaries, body snippets, and links. It does not discuss pagination, rate limits, or auth, but those are less critical for a simple read-only search 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?

Very compact and front-loaded: the core behavior appears first, followed by the key alternative and return summary. Every clause earns its place with no redundancy.

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

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

For a read-only search tool with full schema coverage and annotations covering safety, the description supplies the missing context: query/no-query behavior, sibling routing, and expected return content. No output schema exists, but the description adequately summarizes returns.

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 all three parameters are fully documented in the schema itself. The description reinforces the query semantics and return shape but adds little parameter-level detail beyond what the schema already provides.

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: viewing/searching Moodle announcements and forums. It also distinguishes the query/no-query behavior and names the sibling tool search_ed_threads for Ed discussions, so an agent can identify its scope 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?

Explicitly says what to do without a query (see announcements), what to do with a query (search), and which alternative to use for Ed discussions (search_ed_threads). Usage conditions and exclusions are directly 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?

Adds real behavioral context beyond the readOnlyHint=false annotation: it requires explicit user consent, it is idempotent ('if already logged in, won't open again'), and it triggers an automatic data sync on success. It does not say what happens on failure/cancellation or that it opens an interactive window that blocks, which keeps it from 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?

The consent precondition is front-loaded in the first clause, followed by behavior, then the routing hint to the diagnostic sibling. No redundant or filler sentences.

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 parameters and no output schema, the description covers purpose, precondition, idempotency and the sync side effect, which is nearly all an agent needs. Error/cancellation behavior and what 'success' returns are the only unaddressed pieces.

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 for the description to disambiguate. Baseline 4 applies; the sentence about consent and idempotency is about invocation context rather than parameter 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 and object: opens the local Moodle login window, and it explicitly names the sibling tool (get_monash_status) that should be used instead for diagnostics. An agent can distinguish it from every other sibling without reading 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 precondition ('only after the user has explicitly agreed to re-login') and an explicit exclusion/alternative ('for diagnostics use get_monash_status'). Both when-to-use and when-not-to-use are spelled out.

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 only declare readOnlyHint=false, so the description carries most of the behavioral burden and does add value: it discloses idempotency (no duplicate launch while syncing) and that a full-text index is rebuilt alongside local data. It stops short of stating expected duration, rate limits, or what state changes result, 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?

Three tight clauses with the core action front-loaded, followed by the usage trigger and the sibling routing. 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?

For a zero-parameter action tool with no output schema, the description covers what it does, when to call it, the alternative, and the concurrency guard. It leaves the post-sync result state unstated, but nothing essential to invoking 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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies no arguments are needed by giving a plain trigger-based invocation.

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 (刷新/refresh) plus the exact resources affected (Moodle/Ed local data and full-text index), which no sibling claims. An agent can distinguish it from get_monash_status and the many read-only search/list siblings 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 triggers (user asks for a refresh, or data is stale) and names the alternative for a different need (diagnosing errors → get_monash_status). It also states the when-not condition: if a sync is already running it will not start a second one.

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