moodle-mcp

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 useful ordering ('newest first') and per-course scoping, but omits key behavior: what happens when course_ids is omitted, and how per_course limits results.

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

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

A single compact sentence with the ordering fact front-loaded and no filler. It is arguably too terse for a two-parameter tool, but every word 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?

For a simple read-only list tool with no output schema, the description conveys the essential purpose, but with 0% schema coverage and no annotation detail on defaults, it leaves the parameter behavior unexplained. Adequate but with a clear gap.

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

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

Schema description coverage is 0%, so the description carries the full burden for both parameters — yet it never mentions course_ids or per_course. An agent cannot tell from the text that course_ids=null covers all courses or that per_course defaults to 5.

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 resource (each course's Announcements forum) and the returned items (latest posts), which distinguishes it from moodle_discussion and moodle_search without opening schemas. It stops short of explicitly contrasting with those siblings, but the scope 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?

No when-to-use guidance and no named alternative, even though moodle_discussion, moodle_search, and moodle_notifications are obvious competing sources for course posts. Usage is only implied by the resource named.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine behavioral value by disclosing the returned payload (submission state, grade, feedback), which matters with no output schema present; it does not, however, mention permission/authentication requirements for viewing grades.

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, no filler. The dense field enumeration is front-loaded and each listed item conveys distinct return content; the invocation sentence is short and follows naturally.

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

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

With no output schema, the description correctly carries the burden of describing return values and does so thoroughly. The remaining gap is the 0%-covered parameter pair, whose distinct meanings are not resolved, and no note on error behavior when neither identifier is given.

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

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

Schema coverage is 0% and neither parameter is required, so the description must compensate. It names both parameters and implies they are interchangeable ('Pass assign_id or cmid'), which is real added value, but it never explains what cmid is (course module id) versus assign_id, nor what happens if both or neither are supplied.

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 resource and scope ('One assignment in full') and enumerates exactly what is returned: instructions, attachments, dates, submission types, submissions, grade and feedback. This singular, detail-level framing clearly distinguishes it from the plural sibling moodle_assignments and from moodle_deadlines.

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

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

The only guidance is 'Pass assign_id or cmid,' which tells the agent how to invoke it, not when to choose it. There is no mention of when to prefer this over moodle_assignments, moodle_deadlines, or moodle_course_contents, and no prerequisites or exclusions are 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 establish readOnlyHint=true and openWorldHint=true, so the description's burden is lighter. It adds real behavioral context beyond the annotations: results are sorted by due date, and status values are enumerated (new/draft/submitted/nosubmission) along with the conditional inclusion of grades. It says nothing about pagination or result volume, which matters for an open-world list tool.

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

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

A single, dense sentence with no filler, and the scope/sort/status details are ordered from most to least important. It is efficient, though the trailing 'when include_status is true' clause could be tightened.

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

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

There is no output schema, so the description reasonably sketches the returned fields (due date, status, grade), which is helpful. However, with three parameters at 0% schema coverage, leaving only_open undefined means an agent cannot know whether omitting it returns closed assignments too — a meaningful gap for a discovery tool.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It does explain include_status (adds submission status and grade when true) and partially explains course_ids ('or the given ones'), but only_open goes entirely unmentioned even though it narrows the result set implied by 'All assignments'.

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) with scope (current courses or explicitly given course_ids) and ordering (by due date). The 'All assignments' framing implicitly separates it from the singular moodle_assignment sibling, but no sibling is named outright, so the differentiation is left to inference.

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 description establishes the scope ('current courses (or the given ones)') from which an agent can infer this is the list-across-courses call versus the single-item sibling. There is no explicit when-to-use, no when-not-to-use, and no naming of alternatives such as moodle_assignment or moodle_deadlines.

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 destructiveHint=true, readOnlyHint=false and openWorldHint=true. The description adds genuinely new context: token-permission scoping, that nested params are accepted, and a heuristic that write-named functions should be treated like submissions and confirmed first. This reinforces rather than contradicts 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?

Three short sentences, front-loaded with the 'Escape hatch' framing, then a concrete example, then the safety rule. No filler and every sentence carries 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 an open-world, destructive tool with no output schema and no schema descriptions, the description covers purpose, when to use, parameter shape and the confirmation requirement. Error/failure behavior is not mentioned, but the essentials for calling it correctly are present.

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

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

Schema coverage is 0%, so the description must carry the load, and it does reasonably well: it defines wsfunction as any token-permitted Moodle function and supplies a concrete example with a real function name and nested params object. It does not spell out how invalid function names or malformed params are handled, leaving a small gap.

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 ('call any Moodle web-service function') and frames itself as an 'escape hatch', which implicitly positions it as the generic fallback against the many specific siblings (moodle_grades, moodle_submit_assignment, etc.). It never names a sibling explicitly, so differentiation is implied rather than stated.

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

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

Gives clear context ('any function the token allows') and a concrete rule for write operations: confirm first for save/submit/update/delete/send. It stops short of an explicit exclusion like 'prefer the specific tools when one exists', which is the main guidance an agent needs for an escape hatch.

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 disclosure about the response payload (sections, activity/resource fields, section body text), but says nothing about permissions, pagination, or payload size for a potentially large course.

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 compact sentence that leads with the scope ('every section of a course') and follows with the returned fields. No filler, though the parenthetical is long and slightly dense.

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

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

With no output schema the description does a decent job sketching the return shape, and there is no annotation contradiction. It remains incomplete on the two input parameters and on behavior for large courses, which is the main gap for a read tool of this breadth.

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

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

Schema description coverage is 0%, so the description carries the full burden — yet neither parameter is explained. course_id is never mentioned, and include_descriptions (default true) is only obliquely referenced via 'the section text', with no indication it can be turned off or what it controls.

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 the resource precisely — every section of a course plus its activities/resources — and enumerates the returned fields (cmid, type, name, dates, files, links). That distinguishes it from siblings like moodle_courses and moodle_assignments, though those siblings are never 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: the parenthetical about section text holding weekly readings and 'for next class' notes hints at a use case, but there is no explicit when-to-use, no when-not, and no named alternative among the 17 siblings. An agent must infer that this is the tool for drilling into one course.

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 real value by scoping results to *enrolled* courses and stating that ids are returned, but says nothing about ordering, pagination, 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?

Two sentences, front-loaded with the action and resource, with the parameter values compactly enumerated. No filler; 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?

For a one-optional-parameter list tool with no output schema, the description covers what is returned (ids) and how to filter it. Only ordering/pagination and the precise semantics of each 'which' value are unaddressed, which is minor at this complexity.

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

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

Schema description coverage is 0% and the schema has no enum, so the description carries the burden — it enumerates all four accepted values (inprogress | future | past | all) and marks the default. It does not explain what 'inprogress' means operationally (active vs. recently viewed), leaving a small gap.

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 ('enrolled courses') plus the returned field ('ids'), which cleanly separates it from moodle_course_contents and moodle_assignments. It never names a sibling alternative, so it stops short of full differentiation.

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: calling it returns the user's enrolled courses, and the 'which' values hint at the natural filtering cases. There is no explicit when-to-use statement, no prerequisites, and no pointer to alternatives such as moodle_deadlines or moodle_course_contents.

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 behavioral context beyond that — data staleness ('dates can lag edits teachers make') and conditional result scope ('days_back > 0 also returns overdue items'). It does not mention auth requirements, result volume, or pagination, so it is good rather than exhaustive.

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

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

Two short sentences, purpose front-loaded, no filler. The inclusion of the days_back rule in the opening sentence is slightly utilitarian rather than tidy, but every clause carries information.

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

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

With no output schema and thin annotations, the description should do more: it never describes what a returned deadline entry contains or how results are ordered. It covers purpose, freshness caveat, and a cross-check path, which is adequate but leaves gaps an agent would need.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It explains days_back's behavioral effect well (values > 0 pull in overdue items), but course_id and days_ahead — including the default 14-day forward window — are left entirely unexplained.

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 resource (unfinished assignment/quiz deadlines) scoped to the Moodle timeline, which is a narrower thing than the sibling moodle_assignments' likely full assignment listing. It also names moodle_assignment as the tool to use for authoritative confirmation, so the agent can separate the two without opening a schema.

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

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

Gives clear context for use (checking upcoming/overdue unfinished work) and explicitly routes the agent to moodle_assignment when a deadline is critical, which is the key decision point. It stops short of saying when this tool should not be used at all (e.g. for grades or announcements, which other siblings cover).

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 it returns ALL posts (a scope/volume statement) but says nothing about ordering, pagination, truncation, or what a post object contains. Adequate but thin for a tool whose output could be large.

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 core purpose first and the id-provenance hint parenthetically attached. No wasted words, though the parenthetical slightly interrupts the primary 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?

For a one-parameter read tool with no output schema, the description covers purpose, scope (all posts), and id provenance — enough to invoke correctly. Missing only return-shape/pagination detail, which is a minor gap at this complexity.

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

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

Schema description coverage is 0% and the sole parameter has no description, so the description carries the full burden. It does so by explaining that discussion_id is obtained from moodle_announcements or moodle_read on a forum — a meaningful provenance hint beyond the bare 'integer' type.

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 the resource and scope precisely: 'All posts in one forum discussion' — an agent immediately knows this returns discussion content, not forums or announcements. It does not explicitly name a sibling it is not, but the scope is narrow enough to be 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 parenthetical tells the agent where to get the discussion id (moodle_announcements / moodle_read on a forum), which is a genuine workflow hint and better than nothing. However it never states when to prefer this tool over siblings like moodle_read or moodle_course_contents, nor any prerequisite beyond the id source.

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=false, destructiveHint=false, and openWorldHint=true, so the write-to-disk, non-destructive, network-bound profile is covered. The description adds the default target directory and the returned local path, but says nothing about overwrite behavior, permissions, or failure modes.

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 zero filler that names the action, the default location, and the return value. 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?

With no output schema, the description usefully states that the local path is returned, and annotations cover the safety profile. However, for a 2-param tool with 0% schema coverage it omits how to obtain fileurl and what happens on existing files or errors.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and largely does not. It implies fileurl is a Moodle file URL and repeats the dest_dir default already present in the schema, but gives no format, provenance, or validation detail for the required fileurl.

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 ('Save a Moodle file to disk') plus the default destination and the return value (local path). This clearly differentiates it from read-oriented siblings like moodle_read and moodle_file_text, though it does not name them 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?

No guidance on when to download versus reading a file with moodle_read or moodle_file_text, and no note on where the required fileurl comes from (e.g., moodle_course_contents). Usage is only implied by the verb 'Save'.

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 context: the paginated slice/offset model and the set of accepted file formats, which the agent cannot get from annotations. It omits what happens on truncation boundaries and how slices are delimited.

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, front-loaded with the resource and formats, followed by the pagination rule. Nothing is wasted and no sentence merely restates the tool name.

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

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

With no output schema, the description does provide some return-value context (text, delivered in slices) and the chaining precondition. It would be fully complete if it described the slice response shape (e.g. whether an offset/end marker is returned) and the `max_chars` truncation control.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains two of the three parameters: `fileurl` (provenance from another tool) and `offset` (resume the slice). The `max_chars` parameter and its 40000 default are never mentioned, leaving a real gap in the contract.

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 (extracting text from a Moodle file) and enumerates supported formats (PDF, DOCX, PPTX, XLSX, HTML, plain text), so the purpose is unmistakable. It does not, however, differentiate itself from siblings that also touch files, such as moodle_read or moodle_download, leaving the agent to infer which one to reach for.

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

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

Clearly specifies the precondition — the `fileurl` must come from another tool — and gives explicit continuation guidance ('call again with offset to continue') for long files. It stops short of naming alternatives or stating when a different sibling (e.g. moodle_download or moodle_read) would be preferable.

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, covering the safety profile. The description adds token-scoped permissions ('this token can call'), which is useful auth context, but omits result size, pagination, or matching behavior; with annotations doing the heavy lifting, this is adequate but not rich.

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

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

Two sentences, front-loaded with identity and followed by routing guidance; no filler. The filter example is tucked into parentheses without disrupting flow.

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 discovery tool with no output schema, the description conveys what is returned (function names) and how to narrow results. It lacks detail on result format or pagination, but nothing essential is missing for correct invocation.

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

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

Schema coverage is 0% and the single `match` parameter has no description in the schema. The description compensates by explaining it as a filter with a concrete example, which is meaningful beyond the schema's bare title and default.

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 the exact resource (Moodle web-service function names available to this token) and its role as a discovery index for moodle_call. It clearly distinguishes itself from all sibling action tools by being a read-only listing rather than an action executor.

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 to use it when no dedicated tool fits and names moodle_call as the consumer, so the agent knows when to select it over siblings. The filter example ('calendar') gives immediate operational guidance on the one parameter.

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 readOnlyHint and openWorldHint, so the safety profile is known. The description adds real behavioral value by disclosing the returned field set and the behavior shift when course_id is omitted (aggregate totals instead of per-course items).

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

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

Two tight sentences, front-loading the primary behavior and then the fallback mode, with zero filler.

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

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

For a single-optional-param read tool with annotations covering safety and no output schema, the description supplies what an agent needs: the resource, the return fields, and the conditional behavior. Minor gaps (formatting/pagination) are not critical here.

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

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

Schema coverage is 0% and the schema only labels the param 'Course Id'. The description meaningfully compensates by explaining that supplying course_id scopes results to one course and omitting it returns totals for all courses.

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 resource (grade items) and the fields returned (grade, max, %, weight, feedback), and distinguishes its two modes. Among the siblings, no other tool handles grades, so the resource specificity carries the differentiation.

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

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

Clearly frames the two calling contexts: with course_id it returns one course's grade items, without it returns course totals across all courses. There are no alternatives named, but the conditional usage is explicit enough to guide the call.

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 nothing behavioral beyond that: no mention of pagination, ordering, recency window, or what unread versus read state means in the result. It does not contradict the annotations, but it contributes no context they don't already carry.

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

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

It is a single short fragment with no filler, so it is compact and front-loaded. But brevity here comes from under-specification rather than discipline — a verb and a clause about what is returned would cost little and add much.

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 covering the safety profile, the content-type list is genuinely useful context. Still missing: the action performed, any parameter guidance, and result shape (no output schema exists to cover it), leaving real gaps for an agent deciding whether to call this or a sibling.

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

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

Schema description coverage is 0% for two parameters (limit, unread_only), so the description must compensate and does not. 'limit' and 'unread_only' are relatively self-explanatory names, but the description never mentions either, nor any default (limit=20), ordering, or what 'unread' scopes to.

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 the resource ('the bell-icon notifications') and enumerates the content types it carries, which helps distinguish it from siblings like moodle_announcements or moodle_deadlines. However, it is a bare noun phrase with no verb — it never says whether the tool lists, fetches, marks, or dismisses notifications. An agent must infer the action, so the purpose is only implied.

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 when-to-use guidance and no mention of alternatives, even though siblings such as moodle_deadlines (due dates) and moodle_announcements overlap with the content types listed here. The agent is left to guess whether notifications or those dedicated tools should be preferred.

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 return-content detail by resource type, but does not disclose auth requirements, enrollment constraints, or rate limits.

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

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

The definition is one front-loaded sentence with a compact list of return types. It is appropriately sized and wastes no words.

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

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

No output schema exists, so the description carries the burden of describing return values, which it does for multiple activity types. It is largely complete for invocation, though usage guidance and cmid semantics remain thin.

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

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

Schema description coverage is 0% for the single cmid parameter. The description mentions cmid as the identifier for the activity/resource, giving partial semantic context, but does not define its format or relationship to course/module IDs.

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

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

The description states a specific verb and resource: open any activity/resource by cmid. It also lists the readable content returned for several resource types. It does not explicitly distinguish itself from siblings like moodle_assignment or moodle_discussion.

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: use this when you have a cmid and want readable content for an activity/resource. There is no explicit when-not guidance or named alternative tool to choose instead.

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 usefully adds what is actually searched (activities, files, section text) and the default scoping to current courses, but omits result limits, pagination, or match semantics (substring vs fuzzy).

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 parenthetical is the only compressed element. Every clause conveys information the agent needs.

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

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

For a read-only search tool with two parameters, this is close to adequate, but with no output schema an agent still lacks any sense of result shape, ordering, or cap. The description covers scope but not the outcome of the call.

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

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

Schema coverage is 0%, so the description must compensate: it does explain that `query` is the term to match and that `course_ids` defaults to 'current courses' when not supplied. It adds no syntax or type detail beyond that, leaving the parameter contract thin for a zero-coverage 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 ('Find') and concrete resources ('activities, files and section text') plus the search scope. It is clear enough to distinguish from content-fetching siblings like moodle_read or moodle_course_contents, though it does not name 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?

Usage is implied by the phrase 'across current courses (or the given ones)', which tells the agent this is a keyword search scoped to enrollment. However, no explicit when-to-use, when-not-to-use, or named alternative (e.g. moodle_course_contents for browsing) 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 flag destructiveHint=true and openWorldHint=true; the description adds the crucial specifics that the call REPLACES existing text/files, that the default leaves a draft, and that submit_for_grading finalises and accepts the submission statement. Missing only auth/error behavior, which is minor here.

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

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

Three tight sentences, all load-bearing: what it does, the destructive replacement semantics, and the approval precondition. Front-loaded with the operation before the caveats.

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 destructive mutation with no output schema, the description covers the essential behavioral facts an agent needs before invoking. It omits only edge details like failure handling or whether a prior draft is retrievable, which are secondary.

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

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

Schema coverage is 0%, so the description must carry the load. It maps text_html to 'online text (HTML)' and file_paths to 'local files', and fully explains submit_for_grading's default and effect; only assign_id is left implicit, which is low risk.

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 (Save/submit) and resource (user's submission for an assignment), plus the two content channels it accepts. No sibling tool offers submission, so the agent can distinguish it immediately.

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

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

Gives a clear precondition ('Only call after the user has approved the exact content') and explains the draft-vs-finalise decision via submit_for_grading. It does not name an alternative sibling for read-only assignment inspection, but the when-to-use condition is explicit.

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 value by disclosing the return payload (site name, version, authenticated user), which matters because no output schema exists; it stops short of saying what happens when the connection or auth fails.

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 that identifies the action first and the returned fields second, with no filler or redundancy.

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

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

With zero parameters, a fully covered (empty) schema, and annotations carrying the read-only/open-world profile, the description supplies the missing return-value detail. Only the failure/error behavior when the connection is bad 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?

The tool takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. The description correctly implies no inputs are 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 (check) and resource (connection) and enumerates exactly what it reports: site name, Moodle version, logged-in user. This clearly separates it from data-oriented siblings like moodle_courses or moodle_grades, though it never names an alternative 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 'Check the connection' – an agent can infer this is a connectivity/auth smoke test to run before other calls, but there is no explicit when-to-use, when-not-to-use, or named alternative.

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