PLATO MCP

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description goes further by stating the action is IRREVERSIBLE once dry_run=False and by mandating a preview-and-confirm protocol before the write. That is genuine behavioral context an agent cannot derive from the annotations alone.

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 short blocks: purpose first, then the safety protocol. No filler, and the irreversibility warning is placed immediately after the purpose so it is read before any parameter discussion.

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?

An output schema exists, so the description needn't explain the preview payload, and forum_id discovery is delegated to list_forums in the schema. It stops short of mentioning permission requirements or what happens on duplicate subjects, which are minor residual gaps for a destructive create.

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 dry_run field description already spells out 'call again with dry_run=False (same parameters) to actually post.' The prose largely restates that, adding only mild emphasis. Required fields forum_id/subject/message gain no extra semantics beyond the schema.

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

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

States a specific verb and resource: 'Start a new discussion thread in a forum.' That clearly separates it from the many read-only list_/get_ tools in the siblings. It does not explicitly name add_discussion_post as the reply-oriented alternative, so the boundary with that sibling is left to inference from the wording 'new discussion thread'.

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, ordered workflow: call with dry_run=True (default) first, show the preview to the user, and only re-call with dry_run=False after explicit confirmation. The condition for the mutating call is unambiguous, which is exactly the guidance an agent needs for a destructive tool.

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

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

Annotations already mark this destructive and non-idempotent, but the description adds the crucial behavior not in structured fields: the write is irreversible once dry_run=False and requires a user-confirmation gate. That is exactly the extra context annotations cannot express.

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 lines with zero waste: the irreversibility warning is front-loaded and the procedural steps follow in order. Every 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?

An output schema exists, so return values needn't be explained, and the safety workflow plus parameter meanings are fully covered for a 4-parameter mutation. An agent has everything needed to call this correctly and safely.

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 dry_run property already documents the preview/re-post semantics in detail, so the description mostly restates what the schema carries. The 'same parameters' note is helpful but marginal; baseline 3 fits when 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 and resource ('Reply to a forum discussion thread'), which is clearly distinct from add_discussion (new thread) and post_qna_question. It does not explicitly name those siblings to route the agent, so it falls short of a 5.

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 two-phase workflow: call with dry_run=True (default), show the preview to the user, then call again with dry_run=False only after explicit confirmation. The conditions for each call are stated outright, 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?

The annotations already flag destructive/non-idempotent, but the description adds context the agent cannot get elsewhere: the operation is irreversible, no delete tool exists for private files, removal requires PLATO's UI, and the tool is local-only. That is exactly the extra behavioral context annotations cannot convey.

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 irreversibility warning, then the workflow, then the environment constraint – a sensible priority order. Slightly verbose with some repetition between the description's dry_run instructions and the schema's own dry_run description.

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?

An output schema exists so return values need not be explained, and the description covers the remaining risk surface: irreversibility, absence of a delete path, confirmation protocol, and the local-execution requirement. Complete for a destructive single-upload 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 coverage is 100%, so both parameters are already documented including dry_run's default and re-call semantics. The description reinforces the dry_run confirmation flow and notes to reuse 'same parameters', but adds little syntax or meaning 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 and resource ('Upload a file to this account's Moodle private files area'), scoped to private files, which distinguishes it from every sibling (which are read/list/quiz/forum tools). An agent knows immediately what this does and what it touches.

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 two-step procedure (dry_run=True first, show preview, then dry_run=False only after explicit user confirmation) and a hard precondition ('only works when this server is running locally (stdio)'). Nothing about when to invoke it 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 declare destructiveHint=true and readOnlyHint=false, and the description adds the crucial fact that the operation is IRREVERSIBLE once dry_run=False, plus a recommended confirm-before-commit workflow. This is meaningful context beyond the annotation flags, not a restatement of them.

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 action and the irreversibility warning, then gives the confirm workflow. Every sentence earns its place, though the scope note and workflow could be tightened 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?

Output schema exists, so return values needn't be explained; annotations cover the safety profile; the description supplies the irreversibility, scope limits, and confirm workflow an agent needs to call it safely. Nothing essential is missing for a destructive create 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 all five parameters (including dry_run, timestart, duration_seconds) are already documented in the schema. The description reinforces the dry_run semantics behaviorally but adds little parameter-level 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 and resource ('Create a personal calendar entry') and immediately delimits scope by noting only personal ('user') events are supported, whereas course/group events are not creatable. This clearly separates it from siblings like list_calendar_events and delete_calendar_event.

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 two-step protocol: call with dry_run=True (default) first, show the preview to the user, then call again with dry_run=False only after explicit confirmation. It also states the exclusion (no course/group events), so when-to-use and when-not-to-use are both covered.

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 mark this destructive and non-idempotent, so the low bar is easily passed — and the description adds real value on top: it declares the deletion IRREVERSIBLE once dry_run=False and prescribes a confirm-with-user protocol. That is exactly the behavioral context an agent needs before firing an irreversible write.

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 lines, zero padding: the irreversible warning is front-loaded and the two-step procedure follows immediately. Every sentence carries operational weight.

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?

Annotations cover the safety profile, the schema documents both parameters fully, and an output schema exists so return values need not be described. For a two-parameter destructive tool, nothing an agent needs to invoke it safely 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 schema already spells out both event_id and the dry_run default/loop semantics. The description reinforces the dry_run workflow but adds no syntax or format detail beyond the structured fields, 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 concrete verb+resource ('Delete a personal calendar entry') and adds a scoping constraint — the entry must belong to 'this account' — which implicitly rules out other users' calendars. It does not name the nearest siblings (create_calendar_event, list_calendar_events), but the ownership qualifier is enough to make the target 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?

Gives an explicit procedural rule: call with dry_run=True, show the preview, and only proceed with dry_run=False after the user explicitly confirms. That is strong when-to-use guidance for a destructive tool. It stops short of the 5 bar because it never references any alternative tool or when not to use this one.

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?

Goes well beyond the `readOnlyHint` and `openWorldHint` annotations: it explains the two return modes (saved path vs. inline base64 vs. authenticated URL), the token-bearing URL security risk, allowed file extensions, and local size-limit rejection. That is exactly the behavioral context an agent needs before invoking it.

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

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

The description front-loads the purpose and then organizes behavioral details by environment. It is somewhat long, but the length is justified by the genuinely mode-dependent behavior and security warning; little is redundant.

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 all the complexity an agent needs: required parameter source, environment-specific `save_path` rules, three possible return shapes, extension constraints, size limits, and token-handling warnings. With an output schema present, no important behavioral gap remains.

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 schema already documents the local-required/remote-forbidden semantics of `save_path`. The description reinforces those constraints but adds no new parameter-level detail beyond what the schema provides, so the baseline for high coverage 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 ('Download a course file') and anchors the required `file_url` to its source in `get_course_contents`. This clearly distinguishes it from the sibling listing tool that only returns file metadata.

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

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

Provides clear context for when to use it in each deployment mode (local stdio vs. remote HTTP) and explicitly says not to pass `save_path` remotely. It does not name alternative tools for related tasks, but the usage conditions for this tool itself are unambiguous.

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 read-only safety profile. The description adds genuine value by disclosing what the return does and does not contain (tracking rules yes, watch-percentage and deadline no), which goes beyond the annotations. Minor gap: no note on output shape or size, though an output schema exists.

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 statement, then the comparison to get_course_contents. Efficient overall, though the trailing clause on vod modules runs long and could be tightened without losing meaning.

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-param read tool with an output schema and clear annotations, the description is complete: it explains what is returned, what is not, and when to route elsewhere. 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?

With a single parameter and 100% schema coverage, the schema fully documents course_id (PLATO/Moodle numeric id from list_courses). The description adds no parameter-level meaning beyond this, so 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: retrieving completion status for every activity/module in a course. It clearly distinguishes itself from get_course_contents by noting it returns richer tracking rules. However, it never addresses the nearly identically named sibling get_course_completion_status, leaving a real ambiguity an agent could stumble on.

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 states when to prefer this tool (richer tracking rules like 'must view' vs 'must spend N minutes') and when to prefer a named alternative (get_course_contents for vod modules with watch-percentage and deadline info). Both the positive and negative routing conditions 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=true and openWorldHint=true, so the read-only, remote-data nature is covered. The description adds one genuinely useful behavioral fact — that the result is scoped to 'this account's submission status' — but says nothing about permissions/enrollment requirements or result size.

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 front-loaded sentence with no filler and no redundancy against the schema. It is efficient, though it is perhaps too terse to carry any routing guidance.

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 with full schema coverage, annotations, and an output schema, this is adequate — return values need not be explained. What is missing is what 'details' covers and whether the account must be enrolled, which an agent would need when deciding between this and list_assignments.

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 both course_id and assignment_id documented including their source tools, so the baseline is 3. The description adds no additional parameter meaning beyond what the schema already states.

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 concrete verb (get) and resource (one assignment's details) plus a second data dimension (this account's submission status). The singular phrasing implicitly separates it from list_assignments, but it never names that sibling 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?

Usage is only implied: 'one assignment' signals this is the per-item drill-down companion to list_assignments. There is no explicit when-to-use, when-not-to-use, or prerequisite (e.g., needing course_id from list_courses and assignment_id from list_assignments).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds domain context about the permission model (personal vs course/group entries) but says nothing about freshness of the permission data, caching, or auth requirements; the existing output schema covers the return shape.

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 short sentences with the core purpose front-loaded and the interpretive hint second. The awkward source line breaks cost it nothing, but the phrase 'typically' is a bit hedging for a permissions check.

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, an output schema defining the return values, and annotations covering the read-only profile, the description provides everything an agent needs to decide to call it and how to interpret the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter semantics are missing.

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 (check this account's calendar-management permissions) and clarifies what the answer means by contrasting student accounts (personal entries only) with course/group entries. It is clearly distinguishable from calendar-action siblings like create_calendar_event or list_calendar_events, though it doesn't explicitly name an alternative access-info tool.

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

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

The description implies when the tool is useful (you want to know whether the account can manage course/group calendar entries), but it never states an explicit when-to-use, prerequisite, or alternative. An agent must infer that this should be called before attempting calendar mutations.

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 and openWorldHint, yet the description adds the non-obvious trait that most courses return available=False with an explanatory message, which prevents an agent misreading an empty-looking result as an error. It doesn't touch permission requirements or result variability across courses, so it stops just short of full behavioral coverage.

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

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

The core capability is front-loaded in the first sentence and the fallbacks follow without filler; every clause earns its place. The parenthetical about available=False is slightly dense but carries real 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 single-parameter read tool with an output schema already covering return structure, the description supplies the only things that could be missing: applicability condition, expected common negative outcome, and routing to alternatives.

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 course_id field already explains the numeric PLATO/Moodle id and where to obtain it (list_courses). The description adds nothing further about the parameter, 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 (get) and a precisely scoped resource (account-level course-completion status) rather than generic course data. It explicitly separates itself from the two nearest siblings (get_activity_completion_status and get_course_contents' per-module flag), so an agent can pick the right tool 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 both a precondition (the course must have course-level completion criteria) and the fallback path, naming the exact alternative tools for the common case where criteria don't exist. There is essentially no ambiguity about when to call this versus its siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-dependency profile are covered. The description adds the shape of what is returned (sections, modules, links) but says nothing about ordering, depth of nesting, or whether all modules are included for large courses.

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 front-loaded sentence with no filler; every word (weekly, sections, modules, file links) narrows what to expect.

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?

Output schema exists and the single param is fully documented, so the description only needs to frame scope, which it does. Minor gaps remain around how deep the contents listing goes and whether file links are direct-download URLs.

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 parameter is documented in the schema with source ('from list_courses') and format ('PLATO/Moodle numeric'). The description adds no parameter detail beyond that, 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?

Specific verb ('Get') plus the exact resources returned: weekly sections, modules, and file links for a course. An agent can tell this apart from get_course_module (singular) or list_courses, though it never names those siblings 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?

Usage is only implied — the agent must infer this is the tool for browsing a course's structure once it has a course_id. There is no statement of when to prefer it over get_course_module or list_quizzes, and no preconditions or exclusions.

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

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

readOnlyHint=true and openWorldHint=true already tell the agent this is a safe read against external data, so the description's main addition is the efficiency claim of direct resolution. It does not mention failure behavior for an invalid cmid, course scoping, or that the lookup is a remote round trip.

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 short sentence with the resource and constraint front-loaded; the trailing clause about not fetching the whole course earns its place as differentiation. It could be tightened slightly without losing meaning.

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, annotated, read-only lookup with an output schema, the description covers what the agent needs to decide and invoke. Only edge-case behavior such as invalid or out-of-course cmids is left unstated.

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% with a single documented 'cmid' parameter, so baseline is 3. The description reinforces that the id identifies one module but adds no format, scope, or validity detail beyond the schema.

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

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

Names a specific verb ('Resolve') and resource ('a single course module'), plus the identifying key ('by its id'). It implicitly sets itself apart from get_course_contents by contrast ('without fetching and filtering the whole course's contents'), though it never names that sibling 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?

The description makes the selection condition clear: call this when you already have a cmid and want one module, rather than pulling an entire course and filtering. It doesn't state what to do when the cmid is unknown or cross-course disambiguation is needed, so no explicit exclusions.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context by explaining that classification is derived from course start/end dates rather than a stored status field, which explains why a course may appear in an unexpected bucket.

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 lines, front-loaded with the operation, then the alternative and the practical question it answers. No restatement of the tool name and 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?

An output schema exists and annotations cover read-only semantics, so the description need not explain return values. For a one-optional-parameter read tool, what remains — what it lists, how it filters, and its sibling's role — is fully covered.

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 enum is already fully documented, so the baseline is 3. The description earns the extra point by explaining the underlying criterion (start/end dates) that determines which classification a course falls into, which the enum labels alone do not convey.

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 (list enrolled courses) plus the exact filtering axis (Moodle's own timeline classification based on start/end dates). It explicitly contrasts itself with list_courses ('returns everything unfiltered'), so an agent can pick between the two 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?

Names the alternative (list_courses) and the condition that selects this tool, with a concrete intent phrase ('what am I actually taking right now'). It does not mention search_courses or state when this tool should NOT be used, so it falls just short of fully explicit routing.

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 and openWorldHint, so safety is covered; the description adds the non-obvious behavioral fact that coverage depends on module-level change-tracking support, with a concrete confirmed/not-confirmed module list. It stops short of describing volume or pagination characteristics of the diff, which keeps it off 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 core statement is front-loaded in the first clause, and the trailing parenthetical carries genuinely load-bearing coverage caveats rather than filler. The nested aside is somewhat dense but every clause 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 an output schema present, return-value explanation is unnecessary, and annotations plus the 100%-covered schema handle safety and parameters. The one thing an agent could not infer — silent coverage gaps for custom modules — is exactly what the description discloses.

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 schema already specifies the Unix timestamp semantics of 'since' and the PLATO/Moodle numeric id for 'course_id'. The description adds only 'since a given time', 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?

The description opens with a specific verb and resource ('Get what changed in a course since a given time') and then enumerates the domains covered (configuration, completion, grades, submissions). It explicitly distinguishes itself from the contents/notice-listing siblings, so an agent can tell it apart without inspecting 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 names the exact condition under which this tool under-reports ('this won't catch a new ubfile lecture or ubboard post') and routes the agent to named alternatives ('use get_course_contents/list_notices instead'). That is explicit when-not plus alternative routing, not implied guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that it returns 'all posts' in a thread, implying complete retrieval rather than a filtered subset, but says nothing about pagination, ordering, or authentication 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?

A single tight sentence with the verb and resource front-loaded. It is efficient with no wasted words, though its brevity leaves gaps that could have been filled without sacrificing conciseness.

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 low-complexity, single-parameter read tool with an output schema and full schema coverage, the description covers the core purpose. However, it omits usage context relative to sibling tools and any note on result ordering or completeness, leaving the definition only minimally adequate.

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 discussion_id parameter is documented with an example source ('from get_forum_discussions'). The description adds no parameter meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Get') and resource ('all posts in one forum discussion thread'), making the scope clear. It is distinguishable from get_forum_discussions because it targets posts within a single thread, though it does not explicitly name that sibling.

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?

Usage is implied by the tool name and the discussion_id parameter, but the description itself provides no explicit when-to-use guidance, prerequisites, or comparison to alternatives like get_forum_discussions. The agent must infer the call context from the schema.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral context by equating the returned data with the participant list any enrolled student can see, clarifying authorization/visibility scope. It stops short of noting pagination or volume, but the additions are 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?

Two sentences, front-loaded with the core action and scope, with no filler. The phrasing is slightly informal but each sentence carries information, so it is appropriately sized.

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 single-parameter read tool with an output schema and annotations covering safety, the description supplies the necessary purpose and visibility note. Nothing critical is missing, though pagination and filtering behavior are not mentioned.

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 schema already explains course_id as a 'PLATO/Moodle numeric course id, e.g. from list_courses'. The description adds nothing beyond the schema's parameter documentation, 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 states a specific verb and resource ('Get the list of users enrolled in a course'), clarifies the population ('classmates and instructors'), and notes it includes 'their role'. The resource is distinct enough from siblings like get_user_profile or get_my_course_groups to be identifiable, though no sibling 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?

The second sentence frames visibility ('Same data visible in PLATO's own participant list to any enrolled student'), which implies the use case, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is left largely 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=true and openWorldHint=true, so safety is covered elsewhere; the description adds nothing further. It is silent on whether results are paginated, sorted, truncated, or how large a forum's thread list can be, which is real behavioral context an agent would want.

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 front-loaded sentence with no filler. It is efficient, though the brevity leaves gaps that the other dimensions penalize rather than being a structure problem itself.

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?

An output schema exists so return values need not be explained, and it is a simple one-parameter list tool. Still, for an openWorld read against a live forum, missing notes on result volume, ordering, or forum-type limitations leave it only minimally adequate.

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 forum_id parameter is documented with a usage hint ('e.g. from list_forums'). The description contributes no additional parameter meaning, 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 ('List discussion threads') and bounds the scope to 'one standard Moodle forum,' which implicitly separates it from get_discussion_posts (posts inside a thread) and list_forums (forum inventory). It doesn't name those siblings explicitly, but the resource is unambiguous.

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

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

The phrase 'one standard Moodle forum' hints that non-standard forum types (Q&A, single-discussion) may not be covered, and the schema points to list_forums for obtaining an id, but the description never says when to prefer get_discussion_posts or what to do for other forum types. Usage is implied rather than 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=true and openWorldHint=true, so safety is covered. The phrase 'if visible' adds a genuinely useful behavioral caveat (results may be empty or hidden depending on course visibility settings), but there is no mention of permission requirements, what visibility depends on, or how partial results look.

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 short sentence with no filler, and the visibility caveat is placed where it matters. It is efficient though arguably under-specified rather than optimally concise.

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?

An output schema exists, so return values need not be explained, and the single parameter is fully described. What is missing is the sibling disambiguation an agent needs to pick this tool over get_grades_overview and get_grades_access_info.

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 course_id parameter is well documented in the schema, including the pointer to list_courses. The description adds nothing about the parameter, so the baseline of 3 is appropriate.

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

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

States a verb and resource ('Get ... grade items for a course'), which is better than tautology, but leaves the exact substance of 'grade items' unclear and never distinguishes it from close siblings like get_grades_overview or get_grades_access_info. An agent cannot tell from the text which of the three grade tools returns what.

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

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

The only guidance is the qualifier 'if visible', which hints that results may be withheld, but no when-to-use, prerequisites, or alternative is named. With two sibling grade tools present, the absence of routing guidance leaves selection to guesswork.

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 and openWorldHint, so the safety profile is covered. The description adds real value beyond that by explaining the permission semantics (student self-view vs. teacher/TA all-view) and by previewing the returned canviewallgrades flag with a typical value, which sets callers' expectations.

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 and only three sentences. The parenthetical 'e.g. whether it can see its own grades vs. ... everyone's grades' restates the same idea as the opening clause, a small redundancy that keeps it from a 5.

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?

An output schema exists, so return structure needn't be described, and the description still explains the meaning of the key returned flag and its typical value. Annotations cover safety. Little is missing for a single-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?

Only one parameter, and the schema already documents course_id at 100% coverage including a pointer to list_courses. The description adds nothing further about the parameter, 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?

A specific verb and resource: 'check what grade-related permissions this account has in a course'. It also scopes the answer ('own grades vs. everyone's grades'), which implicitly separates it from get_grades/get_grades_overview. It does not name those siblings outright, so it stops short of a 5.

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?

Usage is implied rather than stated: an agent can infer this is a pre-flight capability check before fetching grades, but the description never says when to prefer it over get_grades or get_grades_overview. The 'Most student accounts will see canviewallgrades=False' line is expectation-setting, not guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context: results are scoped to the account and consolidated "in one call," and it clarifies the return granularity (one grade per course). It does not discuss pagination or limits, hence 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?

Two front-loaded sentences with zero waste: purpose first, sibling routing second. Nothing is repeated from the 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?

An output schema exists, so return structure need not be described. For a no-param read tool, the description plus annotations and schema give an agent everything needed to select and 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?

Zero parameters, so the baseline is 4; the schema reinforces that no inputs are required. The description correctly implies no filtering is needed to invoke it.

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 ("Get this account's overall grade for every enrolled course") and defines the granularity (one summary grade per course). It names the sibling get_grades and contrasts the two, so an agent can distinguish them 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 partitions usage: this tool for per-course summaries, get_grades for individual grade items. The condition that selects each alternative is stated directly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one useful behavioral note — results are conditional ('if any') — but says nothing about what group membership entails, pagination, or access requirements for non-students.

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 short sentence with the scope qualifier placed early and no filler. It is efficient, though it is perhaps too sparse to be exemplary.

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

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

For a simple one-parameter read tool with an output schema and full schema coverage, the description covers the essential scope. Remaining gaps (what groups represent in Moodle, empty-result handling) are minor given the structured fields already 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 description coverage is 100% and the single course_id parameter is documented with a concrete example ('from list_courses'). The description adds no parameter detail beyond the schema, so the baseline of 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 ('Get the groups') scoped to the calling account within a course, which is meaningfully different from siblings like get_enrolled_users or list_courses. It never names a sibling to contrast with, keeping it just short of a 5.

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

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

The phrase 'within a course, if any' implies the scope and that an empty result is possible, but there is no explicit statement of when to use this versus related tools such as get_enrolled_users or get_course_contents. Usage is inferable rather than guided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that the result is the complete body text (as opposed to a listing excerpt), and says nothing about pagination, truncation of long notices, or access requirements for a course the user may not be enrolled in.

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 front-loaded sentence with the resource and the 'full text' scope stated immediately. Nothing redundant and nothing to trim.

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?

Return values are covered by the output schema and both parameters are documented, so the essentials are present for a simple detail-fetch tool. The remaining gap is behavioral: no note on permissions, cross-course id validity, or what happens for an invalid post_id.

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 both required ids are documented in the schema with concrete sourcing hints ('e.g. from list_courses', 'e.g. from list_notices'). The description contributes no additional parameter meaning, so the baseline of 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?

Specific verb (get) plus resource (notice/announcement) with a scope qualifier ('full text of one'), which implicitly differentiates it from the sibling list_notices that returns previews. It does not name the sibling explicitly, so it falls just short of 5.

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?

Usage is only implied: 'one notice' signals the single-item counterpart to list_notices, and the schema description ('post id, e.g. from list_notices') reinforces the list-then-detail flow. There is no explicit when-to-use statement, no exclusions, and no mention of alternatives such as get_qna_detail or get_course_updates_since.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds what is summarized (counts and total size) but nothing about aggregation scope, latency, or edge cases such as an empty files area; an output schema also covers return structure.

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 front-loaded sentence with the resource first and the returned fields in parentheses; nothing is wasted. Only the odd embedded line breaks keep it from a 5.

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 no-parameter, read-only summary tool with an output schema and annotation coverage, the description is essentially complete. A note on what happens when the private files area is empty would close the remaining 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?

The tool takes zero parameters, so parameter semantics is baseline 4. The description correctly implies no arguments are needed by scoping everything to 'this account's' files area.

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 ('Get a summary ... of this account's Moodle private files area') and names the summarized fields (file/folder count, total size). It is clearly distinguishable from siblings like add_private_file or download_course_file, though it never says so 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?

Usage is only implied: an agent can infer this is the cheap metadata check before listing or downloading private files. There is no explicit when-to-use/when-not or reference to add_private_file as the mutation counterpart.

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 and openWorldHint, so the safety profile is covered. The description usefully discloses that replies are omitted from the result, but then defers to 'see issue #23', an internal tracker reference that conveys nothing actionable to an agent.

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 short sentences with the core purpose front-loaded and no filler. The 'see issue #23' clause is the one piece that does not earn its place for an agent reader.

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?

An output schema exists, so return values need no explanation, and both parameters are fully documented in the schema. What is missing is routing context (how this relates to list_qna) and a meaningful replacement for the dangling issue reference.

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 schema already tells the agent that post_id comes from list_qna and course_id is a PLATO/Moodle numeric id. The description adds no parameter meaning beyond that, 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 ('Get one Q&A question's text') and narrows the scope to a single question, which implicitly separates it from list_qna. It never names the sibling it complements, so differentiation 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?

There is no explicit when-to-use or when-not-to-use guidance relative to list_qna or get_discussion_posts. The only scoping statement is a content exclusion ('Does not include replies'), which describes output, not invocation conditions.

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

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

Annotations already cover read-only/open-world safety, so the raised bar is met by the 'UNVERIFIED against a real quiz' caveat and the instruction to sanity-check output, which is genuine behavioral context an agent could not get from structure. It stops short of saying what a blocked result looks like or listing all block reasons, keeping it a 4 rather than 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?

Two tight sentences with the purpose front-loaded and the example block reasons parenthetical. Zero waste, though the UNVERIFIED caveat is slightly buried mid-sentence.

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?

An output schema exists and annotations cover safety, so the description needn't explain return values. For a single-parameter read-only check, the description covers purpose, sequencing, and the reliability caveat adequately.

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

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

With a single parameter at 100% schema coverage and an inline schema description ('Quiz id, e.g. from list_quizzes'), the schema already does the work. The description adds nothing about the parameter itself, 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 uses a specific verb ('Check') and a clear resource (quiz access for this account), and it explains what the return value answers ('whether... can currently attempt a quiz, and why not if blocked'). It relates itself to start_quiz_attempt but doesn't differentiate from the many other read-only quiz siblings (get_quiz_attempts, get_quiz_best_grade).

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?

'call this before start_quiz_attempt' gives explicit pre-requisite sequencing, and 'sanity-check the result' sets expectations. It doesn't state when not to use it or name alternatives, but the ordering guidance is clear and actionable.

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

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

Beyond annotations, it discloses that each question's `html` is Moodle's own rendered form, that the agent must parse it for field names, and that the behavior is UNVERIFIED against a real quiz. Those are meaningful output-format and reliability caveats not captured by readOnlyHint or openWorldHint.

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 main action, followed by the parsing requirement and the verification caveat. There is no filler; every sentence contributes actionable 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?

The output schema and annotations handle return values and safety, while the description supplies the essential missing context: the HTML is Moodle-rendered, must be parsed for field names, and has not been verified against a real quiz. That is sufficient for an agent 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%, and both the `page` (0-indexed) and `attempt_id` parameters are already documented in the schema. The description reinforces page scoping but adds no syntax, format, or constraint details beyond what the schema 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 states a specific verb and resource ('Get the questions') and narrows scope to 'one page of an in-progress quiz attempt'. The 'in-progress' qualifier implicitly distinguishes it from finished-attempt sibling tools such as get_quiz_attempt_review and get_quiz_attempt_summary.

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 clear workflow guidance: call this before save_quiz_attempt_responses/process_quiz_attempt, and parse the HTML to identify answer-field names. It names the downstream alternatives but does not explicitly state when not to use this tool or compare it against get_quiz_attempt_review.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds a valuable reliability caveat ('UNVERIFIED against a real quiz') and notes the tool operates on a finished attempt, but lacks details on permissions, rate limits, or error behavior. With annotations carrying the main behavioral signals, a 3 is appropriate.

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

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

Two sentences with no wasted words, and the core purpose is front-loaded. The reliability caveat in the second sentence is substantive and 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?

An output schema exists, so return values needn't be explained. With 100% schema coverage and read-only annotations, the description is nearly complete, but it could better situate the tool among its many quiz-attempt siblings to fully guide selection.

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 (attempt_id and page) are fully documented in the schema. The description adds only marginal semantics by implying attempt_id must reference a completed attempt. Baseline 3 is correct when 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?

The description states a specific verb ('Get') and resource ('grade and per-question review for a finished quiz attempt'), making the tool's core function clear. However, it does not differentiate itself from sibling tools like get_quiz_attempt_summary or get_quiz_attempt_data, leaving the agent to infer the distinction.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, nor does it state exclusions or prerequisites. The phrase 'finished quiz attempt' implies a precondition but stops short of actionable usage instructions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the loose scoping notion of "this account's past attempts" — it says nothing about result volume, pagination, whether in-progress attempts are included, or ordering, which are the details that matter for a read list call.

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 front-loaded sentence with no filler, so nothing is wasted. However, its brevity comes from omission rather than economy — the same one line could have carried disambiguation without bloat.

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

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

The output schema exists, so return shape needn't be explained, and there is only one well-documented parameter. What is still missing for a tool in this crowded quiz-attempt family is a statement of what makes this list result different from the per-attempt detail siblings.

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?

Only one parameter and the schema documents it at 100% coverage, including the hint to obtain it from list_quizzes. The description's "one quiz" corroborates that, but adds no format or edge-case 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 concrete verb and resource: retrieving the account's past attempts for one quiz. The purpose is immediately understandable, but the sibling set contains get_quiz_attempt_data, get_quiz_attempt_summary, get_quiz_attempt_review, and get_quiz_best_grade, and the description does nothing to distinguish this list-level call from those.

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

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

There is no guidance on when to choose this over the several related quiz-attempt siblings, and no stated preconditions (e.g. whether the quiz must have attempts, whether it covers all users or just the caller). The agent must infer routing entirely from the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a meaningful caveat: 'UNVERIFIED against a real quiz', which warns about reliability, but it does not discuss auth, rate limits, or other behavioral traits beyond this single note.

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, front-loaded with the core purpose, and the caveat follows efficiently. Every sentence adds value 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?

The tool is simple (one required parameter), has annotations covering safety, and an output schema that explains return values. The description covers scope and a reliability caveat, making it nearly complete for an agent to call correctly, though explicit sibling differentiation 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 attempt_id parameter is documented with an example. The description adds no additional meaning beyond what the schema already provides, so 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?

The description states a specific verb 'Get' and resource 'summary of all questions in an attempt', with qualifying detail '(answered/unanswered), across all pages'. It is clear what the tool does, but it does not explicitly differentiate from sibling tools like get_quiz_attempt_data or get_quiz_attempt_review.

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

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

The phrase 'across all pages' implies this tool gives an aggregated overview rather than per-page details, but there is no explicit guidance on when to use it versus alternatives such as get_quiz_attempt_data. Usage is only implied, not 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 and openWorldHint, so the description needn't carry the safety profile. It does add the meaningful edge case that no grade is returned unless an attempt has been graded, which is real behavioral signal beyond the annotations, but it says nothing about the return shape for ungraded cases beyond that.

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 front-loaded sentence with no wasted clauses; the scope and conditional caveat arrive immediately. The line-wrap formatting is the only minor blemish.

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 one required parameter at full schema coverage, annotations covering read-only behavior, and an output schema handling return values, the description covers purpose, scope, and the ungraded edge case adequately. Only explicit sibling routing 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 schema itself points the agent to list_quizzes for obtaining the id, so the structured data does the heavy lifting. The description adds no parameter elaboration beyond what the schema already states.

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 ('Get this account's best grade on one quiz') with a scope qualifier ('this account's') and a best-grade aggregation that distinguishes it from a plain attempt listing. It doesn't name a sibling explicitly, but 'best grade on one quiz' contrasts clearly with get_quiz_attempts and get_grades without that.

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

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

The conditional 'if any attempt has been graded' implies the tool only returns a grade when a graded attempt exists, which is useful context. But there is no explicit when-to-use vs alternatives, no exclusion, and no naming of sibling tools like get_quiz_attempts or get_grades_overview.

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 annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful context that the tool reports visibility for marks, feedback, and right answers, but it does not disclose auth requirements, rate limits, or other behavioral details beyond the schema.

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

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

The description is a single front-loaded sentence with no redundant or wasted text. It immediately identifies the action and the information being checked.

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

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

The tool has rich schema coverage, an output schema, and annotations covering its read-only nature. The description is sufficient for calling it correctly, though it could better situate the tool relative to related quiz review and access siblings.

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 parameters are documented in the schema. The description reinforces the attempt scope with 'for a quiz's attempts,' but adds no syntax or format details 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?

The description states a specific verb and resource: checking which review details an account may see for a quiz's attempts. It is clear, but it does not explicitly distinguish this permission-check tool from nearby siblings such as get_quiz_attempt_review or get_quiz_access_information.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The phrase 'allowed to see' hints at permission gating, but the agent must infer that this should be used before requesting actual review details.

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 declare readOnlyHint=true and openWorldHint=true, and the description does not contradict them. It adds examples of the feedback text but does not disclose auth needs, rate limits, or edge-case behavior beyond what annotations and schema already cover.

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 definition is a single front-loaded sentence with useful parenthetical examples and no filler. Every clause contributes to identifying the resource and the lookup.

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

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

For a simple two-parameter read tool with annotations and an output schema, the description adequately explains what is fetched. It could note behavior when no feedback is configured, but that is minor given the output schema exists.

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 quiz_id and grade are already documented in the schema. The description's phrase 'at a given grade' reinforces the grade parameter but adds no format or constraint details beyond what the schema 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 ('Get'), resource ('grade-boundary feedback text configured for a quiz'), and scope ('at a given grade'). It is distinguishable from sibling quiz getters such as get_quiz_best_grade or get_quiz_attempt_review, though it does not explicitly name alternatives.

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

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

The description implies usage when retrieving configured grade-boundary feedback for a specific quiz and grade, but gives no explicit when-to-use, when-not-to-use, or sibling alternatives. The example feedback strings clarify intent but not tool selection.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered by structured data. The description adds the pre-attempt use case and example return values, but says nothing about access requirements, whether question types vary per attempt, or how partial visibility (e.g. random questions) affects the list.

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 tight sentence with the purpose front-loaded and examples in a parenthetical that genuinely clarifies the return values. Nothing is wasted, though there is no structure beyond the single clause.

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?

An output schema exists, so return format needn't be explained, and for a read-only informational lookup the description covers purpose and motivation adequately. Minor gaps remain around permissions and whether the result differs before vs. during an attempt.

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 quiz_id parameter already points to list_quizzes as its source, so the schema does the heavy lifting. The description adds no extra meaning about the identifier, which is the correct baseline-3 outcome for a fully documented one-parameter schema.

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

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

States a specific verb and resource ("List the question types used in a quiz") and makes the return shape concrete with example values like 'multichoice', 'truefalse', 'essay'. It is distinguishable from siblings such as get_quiz_access_information or get_quiz_attempts, though it never explicitly contrasts itself with them.

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?

"Useful to know what kind of answers to expect before starting an attempt" gives a clear usage context that ties it to the start_quiz_attempt workflow. It stops short of naming alternatives or stating exclusions, so it falls just below the explicit when/when-not bar.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful ordering semantics, but says nothing about how many courses are returned, the recency window, 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?

A single sentence with no waste; the resource and ordering are both front-loaded.

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

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

With an output schema to describe return values and no parameters to document, the description is nearly complete. The only gap is the lack of any bound on how many 'recent' courses are returned.

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?

There are zero parameters, so the baseline is 4. The description adds no parameter detail, but none is needed.

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 ('recently-accessed courses') plus the ordering ('most recent first'). It is clearly distinct from list_courses or search_courses in intent, though it never names a sibling to route away from 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?

The 'recently-accessed' scope implies when the tool applies, but there is no explicit when-to-use guidance versus list_courses, get_starred_courses, or get_courses_by_timeline, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds real behavioral value by disclosing the account-wide scope and 'most recent first' ordering. It does not state a result cap or how 'recent' is bounded, which is a minor gap.

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 front-loaded sentence that packs scope, content type, and ordering with no waste. Nothing redundant or buried.

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 an output schema present and no parameters, the description needn't explain return values, and annotations cover safety. Only the recency window or item-count limit is left unspecified, a small but real 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?

The tool takes zero parameters, so there are no parameter semantics to explain and no schema coverage gap to compensate for. Baseline 4 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 ('Get') and resource ('recently-accessed course modules (files, assignments, etc.) across all courses'), plus the sort order. The 'modules/items across all courses' framing implicitly distinguishes it from get_recent_courses, though it never names that sibling 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?

Usage is only implied by the phrase 'recently-accessed.' It does not say when to choose this over get_recent_courses or get_course_contents, nor any preconditions. An agent must infer the choice from the resource wording.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered and the description only needs to add context. 'if any' usefully warns the result set may be empty, but nothing else is disclosed about ordering or scope of 'starred'.

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 front-loaded sentence with no filler, appropriately sized for a no-argument read tool. It is terse to the point of omitting useful routing context, but nothing in it is wasted.

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

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

With an output schema, full annotation coverage, and no parameters, the description carries little burden and covers the essentials. The remaining gap is the absence of any pointer to the general course-listing alternatives, which is minor given the tool's simplicity.

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. There is nothing for the description to disambiguate at the parameter level.

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 ('Get') and resource ('starred/favourited courses') scoped to 'this account', so an agent can distinguish it from list_courses or search_courses by the starred qualifier. It does not explicitly name a sibling, which keeps it short of a 5.

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?

No guidance on when to use this instead of list_courses, get_recent_courses, or search_courses, and no prerequisites stated. The only usage cue is the implicit 'if any', which hints the result may be empty but doesn't route the agent anywhere.

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 and openWorldHint=true already cover the safety profile, so the description owes the agent extra context and supplies almost none. It does not say whether results are paged, ordered by recency, capped by a server-side maximum, or what "this account" implies about auth scope.

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 short, front-loaded sentence with no filler or repetition. It is efficiently structured, though the brevity borders on under-specification rather than tightness.

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?

An output schema exists, so return values need not be described, and the single param is fully documented in-schema. However, the unresolved ambiguity with get_unread_notification_count and the undefined "PLATO" term leave real gaps for an agent choosing between tools.

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?

There is a single optional parameter and schema description coverage is 100% ("Maximum number of unread notifications to return"), so the schema already does the work. The description adds no meaning about ordering, truncation behavior, or what happens when limit is omitted, so the baseline of 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?

"Get this account's unread PLATO notifications" gives a clear verb (get) and resource (unread notifications), but leaves "PLATO" undefined and, more importantly, does not differentiate from the sibling get_unread_notification_count, which an agent could easily confuse with this 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?

No when-to-use guidance is offered. The obvious question — fetch full unread notifications vs. just call get_unread_notification_count — is never addressed, and no prerequisite, pagination, or freshness context is given.

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 and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: the PLATO site-wide messaging disablement means this counts notifications only, not conversation messages — a domain fact an agent could not infer. It does not discuss freshness or polling cost beyond 'cheaper', keeping it just 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?

Two sentences, front-loaded with the action and the cost/alternative comparison, with the caveat second. No redundant restatement of the name or annotations.

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?

Zero parameters, an output schema covering the return value, and annotations covering safety — the description fills the remaining gap with the sibling routing and the messaging-disabled caveat. 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?

Zero parameters, so there is no parameter semantics to explain; the baseline applies. The description correctly implies no filtering arguments are needed by framing it as a simple account-level count.

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 and resource ('Get a count of this account's unread notifications') with explicit scope ('this account's'). It is clearly distinguished from the sibling get_unread_messages by contrasting count-only vs. content.

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

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

Names the alternative (get_unread_messages) and the condition that should send the agent there ('when you don't need the content'), plus a cost rationale ('a cheaper check'). The note about messaging being disabled clarifies that a message-count tool is not the substitute here.

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 (readOnlyHint=true, openWorldHint=true) and an output schema documents the return shape, so the description's job is to add what structured fields can't. It does so by disclosing the urgency sort order, the 'now onward' time boundary, and the non-obvious behavior that results may include activity types absent from sibling tools. It stops short of noting pagination behavior or how 'urgency' is computed, which keeps it below 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?

Roughly two sentences, front-loaded with what the tool returns and immediately followed by the differentiator against alternatives. No restated title, no filler, and the parenthetical examples carry real information.

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

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

For a read-only, one-optional-parameter tool with a published output schema and read-only/open-world annotations, nothing an agent needs in order to select and invoke it correctly is missing. Selection rationale, ordering, time window, and coverage relative to siblings are all 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?

With a single optional parameter at 100% schema description coverage, the schema already explains 'limit' fully, so the baseline is 3 by the rubric. The description earns a small upgrade because 'from now onward' and 'sorted by urgency' clarify the semantics of what is being limited — an urgency-ordered forward-looking window rather than an arbitrary page — which is genuinely additive context for calling the tool with a sensible limit.

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

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

The description states a specific verb and resource — 'Get Moodle's own "what needs action soon" feed' — with concrete examples (assignments due, video lectures with a watch deadline) and an ordering rule (sorted by urgency, from now onward). It also explicitly distinguishes itself from the nearest alternative (combining list_assignments + get_calendar_events), so an agent can separate it from siblings 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 names the alternative approach — combining list_assignments + get_calendar_events — and states the condition under which this tool is better: it is Moodle's own cross-activity prioritized view and may surface activity types (e.g. vod watch deadlines) that those tools miss. That is an explicit use-this-not-that rule rather than implied usage.

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 read-only safety profile, and the description adds real context beyond them: the payload is largely collapsed-section UI state and won't be meaningful standalone. That warns the agent about noisy, low-signal data, which annotations cannot express.

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 short sentences, with the core action front-loaded and the caveat immediately after. Nothing is wasted, though the caveat is hedged with a vague 'most of these' rather than a definite characterization.

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?

An output schema exists, so return values need not be explained, and there are no parameters to document. Given the simplicity, the description supplies adequate context, with only the absence of routing to get_user_profile as a 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?

There are zero parameters, so the baseline is 4; the description neither needs nor omits any parameter guidance. It does clarify the implicit scope ('this account's') rather than accepting a user identifier.

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 and resource ('Get this account's Moodle user preferences'), so an agent knows exactly what it retrieves. It does not explicitly distinguish itself from close siblings like get_user_profile, which keeps it from a 5.

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

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

The note that most values are internal UI state implies this tool is low-value on its own, which is a useful implicit caution. However, it never states when to call it versus get_user_profile or other reads, and no positive use case is given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine value by flagging the PII sensitivity and the course-scoping constraint that governs whether the lookup succeeds, going beyond the annotations.

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

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

A single tight sentence with the scope constraint front-loaded. The 'see docs/pii_review.md' pointer is a dangling reference an agent cannot follow, slightly diluting an otherwise efficient statement.

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?

An output schema exists and the input schema is fully documented, so the description only needs to carry scope and privacy context, which it does. The one gap is behavioral: it doesn't say what happens when the accounts don't share the course (error vs empty).

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 schema already explains that omitting userid returns the caller's own profile and that course_id must be shared. The description reinforces the 'shared course' semantic but contributes no format or edge-case detail beyond the schema.

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

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

States a specific verb and resource ('Get a user's profile') plus a scope qualifier ('scoped to a shared course'), and explicitly negates a plausible misreading ('not a global user search'). It stops short of naming the actual sibling that handles enrolled users (get_enrolled_users), so differentiation is partial.

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

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

The parenthetical clarifies the boundary condition (course-scoped, not global), which implies when to use it. However, it never states when to prefer get_enrolled_users or the account's own profile path, and defers to an external doc the agent cannot read.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds only that due dates are surfaced in the result, which the existing output schema likely covers already; no volume, pagination, or permission context is given.

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 11-word sentence with the resource and scope front-loaded and zero filler. 'with due dates' is the only optional clause and it earns its place by hinting at returned 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?

With 1 required param, full schema coverage, annotations, and an output schema, the description does enough to call the tool correctly. The remaining gap is routing: nothing tells the agent how this relates to get_assignment_detail or get_course_contents when both could answer an assignment question.

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 there is a single required parameter, so the schema already carries the semantics. The description's 'one or more courses' usefully confirms that course_ids is a multi-value array rather than a single id, but adds nothing on format or limits.

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 assignments") and scopes it to one or more courses with due dates. An agent can distinguish it from get_assignment_detail and submit_assignment by the plural/list framing, though no sibling 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?

Usage is only implied: 'list across one or more courses' suggests bulk retrieval rather than a single-assignment fetch. There is no explicit when-to-use / when-not-to-use guidance nor a pointer to get_assignment_detail for a single assignment, which matters in a 50+ sibling surface.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds the useful detail that only future events within a window are returned (the "upcoming" scoping), but it says nothing about ordering, pagination, or whether recurring events are expanded.

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 front-loaded sentence with zero filler that conveys action, resource, and scope immediately.

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?

An output schema exists, so return values need not be explained, and the single parameter is well documented. However, for a tool sitting among many calendar-adjacent siblings, the absence of any routing guidance leaves a real gap in what the agent needs to choose 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% and the single days_ahead parameter is documented in the schema with its default of 14 days. The description only restates the parameter by name, adding no format or edge-case detail, 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 (calendar events) plus a temporal scope (upcoming within days_ahead days). It does not distinguish itself from the sibling get_upcoming_action_events, so the agent must infer the difference, but the tool's own function is 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?

There is no guidance on when to use this tool versus alternatives such as get_upcoming_action_events or get_recent_items, and no prerequisites or exclusion conditions are given. The agent is left to infer selection criteria from names alone.

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 annotations already indicate readOnlyHint=true, so the description's reinforcement of read-only behaviour is less critical. The description adds valuable context beyond annotations by explicitly stating that message reading/sending is unsupported, preventing the agent from expecting message content. It does not cover pagination or rate limits, but with annotations and an output schema that gap is minor.

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

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

The description is two sentences and front-loads the core purpose before the important limitation. 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 one-parameter schema, existing output schema, and annotations, the description covers the essential purpose and the key functional limitation. It could clarify what 'activities' means in the returned data, but the output schema likely handles that.

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 single parameter 'course_ids' is fully documented in the schema, and the description does not add further detail such as array format, maximum length, or ID source. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('Chat (real-time chat room) activities') and scopes it to one or more courses. It clearly distinguishes the tool from message-reading tools by stating that message reading/sending is unsupported, though it does not explicitly contrast with a named sibling.

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

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

The description provides an implied usage context (listing chat activities for courses) and a clear exclusion ('Reading/sending chat messages is not supported'). However, it does not name an alternative tool or state when an agent should prefer this over other listing tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description earns credit for disclosing a real limitation beyond that: voting is not supported by this server, so the agent knows not to pursue a write path elsewhere. It stops short of describing multi-course aggregation behavior or error handling for invalid course 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?

Two very short sentences with no filler, and the core purpose is front-loaded ahead of the limitation. Every clause 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?

An output schema exists, so return values need no explanation, and the single required parameter is fully documented. The description covers purpose, scope, and the read-only limitation. A minor gap remains around whether results are grouped by course or flattened, 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?

There is a single parameter with 100% schema description coverage, so the schema already explains 'course_ids'. The description only restates the cardinality ('one or more courses'). Baseline 3 for a fully documented single parameter.

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

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

States a precise verb and resource ('List Choice activities') and disambiguates the resource by glossing it as a 'single-question poll', which separates it from the many other list_* sibling tools (list_surveys, list_feedbacks, list_quizzes). The scope ('across one or more courses') tells the agent it operates multi-course in a single call.

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?

Usage is only implied: an agent can infer it should call this when it needs read-only visibility into Choice activities. There is no explicit when-to-use/when-not statement and no named alternative (e.g., how this differs from list_surveys for multi-question polls). The 'voting is not supported' clause is a capability boundary, not routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and externality are covered. The description adds only the scope of the account; it says nothing about ordering, pagination, or whether archived/completed courses are included, so the agent learns nothing beyond what the annotations and the sentence already imply.

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 front-loaded sentence with no filler; the scope constraint is stated immediately. It is efficient, though it leaves no room for the disambiguation that would make it stronger.

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 a published output schema, the description does not need to explain return values, and it is adequate at that minimum. The remaining gap is contextual: given four course-listing siblings, it should say what makes this the right one to call (e.g. the complete enrollment list with no filtering).

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 is 4. There is nothing parameter-related the description could add or omit.

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 clear verb+resource ('List the courses') plus the scope qualifier 'the logged-in PLATO account is enrolled in', which pins down whose courses are returned. It does not, however, distinguish this from sibling tools like search_courses, get_recent_courses, or get_starred_courses, which an agent could easily confuse it with.

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?

Usage is only implied: the 'enrolled in' framing suggests it is the unfiltered full-enrollment listing, contrasted implicitly with filtered search/recent variants. No explicit when-to-use or when-not-to-use guidance, and no sibling is named as an 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 and openWorldHint=true, and the description is fully consistent with them ("this tool is read-only coverage only"). It adds real behavioral value beyond the annotations by disclosing that the listing is activity-level only and that entry reading/adding is out of scope for the server, preventing a failed call pattern.

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 short sentences with the capability front-loaded and the scope limit second, which is the right ordering. The closing clause 'read-only coverage only' is slightly redundant with the opening 'List', costing a bit of tightness.

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 an output schema present, return values need not be described, and the single required param is fully specified in the schema. What remains adequately covered is the read-only, activities-not-entries boundary; only a pointer to the alternative for entry data would improve it.

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 param (course_ids) is fully documented in the schema, so the baseline of 3 applies. The phrase "one or more courses" lightly corroborates that the parameter accepts multiple ids, but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (List) and resource (Database "mod_data" activities) with scope ('across one or more courses'), which is enough to separate it from unrelated siblings like get_course_contents or list_quizzes. It does not, however, explicitly contrast itself with the many other list_* siblings (list_lessons, list_h5p_activities, etc.) that share the same pattern.

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

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

The description scopes the tool by exclusion ("Reading/adding entries is not supported by this server"), which tells the agent this is list-only and cannot fetch entry contents. It gives no positive when-to-use trigger and names no alternative sibling for the entry-level data, leaving the routing decision partly 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds genuinely new information: the server has no survey-response capability at all, so an agent shouldn't hunt for a submit tool. It does not mention pagination or result volume, but the key behavioral fact is disclosed.

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

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

Two short sentences, front-loaded with the purpose before the scope constraint. The awkward line wrapping adds no information but the content itself is tight and waste-free.

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 read-only list tool with a full schema and an output schema, the description covers what is needed: what is listed, the course scope, and the read-only limitation. Only the relationship to list_surveys is left unexplained.

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

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

With a single required parameter and 100% schema description coverage, the schema already carries the semantics. The description's 'one or more courses' confirms the array accepts multiple ids, which is a small addition over the schema 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 and resource (list feedback/survey activities) and the scope (across one or more courses), which an agent can act on directly. It is nearly distinguishable from siblings, though calling feedback '(survey)' blurs the line with the separate list_surveys tool.

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

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

The description gives a clear usage boundary -- this tool only reads, responding to surveys is not supported -- which tells the agent what it cannot do here. It stops short of naming when to pick this over list_surveys or how the two differ.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful scope context ('standard Moodle forums', 'separate, less-commonly-used mod_forum module'), but it does not discuss return behavior, pagination, or privacy constraints beyond what the output schema already provides.

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 compact sentences with zero waste. The primary purpose is front-loaded and the exclusion follows immediately, making it easy to scan.

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

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

For a read-only listing tool with a single fully documented parameter, annotations, and an output schema, the description covers purpose and key exclusions. It could be slightly more complete by mentioning the relationship to get_forum_discussions, but no critical information is missing.

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

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

Schema description coverage is 100%, so the course_ids parameter is already documented. The description mirrors that semantics ('across one or more courses') without adding format or validation details, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('List standard Moodle forums') and scopes it to one or more courses. It explicitly distinguishes itself from list_notices/list_qna, so an agent can identify the right tool 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 NOT to use this for PLATO's notice/Q&A board and names list_notices/list_qna as alternatives. However, it does not address the closely related sibling get_forum_discussions, which an agent might confuse with listing the forums themselves.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful context beyond that: this server only supports listing, not reading or adding entries, which prevents an agent from assuming entry-level access after calling it.

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

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

Two short sentences, front-loaded with the primary action. The second sentence is slightly redundant in phrasing ('read-only coverage only') but earns its place by flagging the capability limitation.

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 an output schema present and the sole parameter fully documented in the schema, the description needs only to state purpose and scope limits, which it does. Nothing critical for correct invocation is missing, though a note on multi-course behavior (e.g. per-course grouping) would be nice.

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% for the single required parameter (course_ids), so the schema fully documents the input. The description adds no syntax, cardinality, or cross-course semantics beyond what the schema already states, so 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+resource ('List Glossary activities') and scope ('across one or more courses'), which is enough to distinguish it from the many list_* siblings by resource type. It does not explicitly differentiate from broader tools like get_course_contents that might also surface glossary items, but the core purpose is unambiguous.

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

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

The description gives clear context for when this tool applies (listing) and explicitly rules out entry reading/adding, which helps selection. It stops short of naming an alternative tool for entry-level access, so it is not fully explicit routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral information by ruling out attempt-result retrieval, but it says nothing about pagination, empty-course behavior, or cross-course aggregation limits for a multi-course query.

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 short sentences with the purpose front-loaded and the scope limit immediately after. The second sentence is slightly garbled ('read-only coverage only'), a small blemish on an otherwise tight definition.

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 one fully documented parameter, an output schema to explain returns, and annotations covering read-only/open-world behavior, the description carries the only remaining burden: stating what the tool does not return. It does that. Nothing an agent needs in order to call this 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?

There is a single parameter at 100% schema coverage, where the schema already describes it as 'One or more course ids'. The phrase 'across one or more courses' in the description confirms the array-of-ids semantics but adds nothing beyond the schema, which is the expected baseline.

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

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

The description states a specific verb ('List') and a specific resource ('H5P interactive-content activities') with a scope ('across one or more courses'). The resource name is distinctive enough to separate it from siblings like list_scorms, list_quizzes, or list_lessons, though it never names a sibling 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?

'Attempt results are not supported by this server' excludes one adjacent use case, which is useful negative guidance. However, there is no positive routing guidance: it does not say when to prefer this over list_course_contents or the other list_* activity tools, leaving the agent to infer selection from the resource name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so repeating "this tool is read-only coverage only" adds little. The useful addition is that lesson-taking is outside this server's scope, which prevents wrong tool attempts, but nothing is said about pagination, response shape, or volume.

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 short sentences with the purpose front-loaded, followed by the scope caveat. The phrasing "read-only coverage only" is slightly redundant, but nothing is padded.

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