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

Since no annotations are provided, the description carries the full burden. It discloses that the tool is 'Non-destructive: data, enrolments and teacher access stay intact,' which is valuable behavioral context beyond the schema. It also implies reversibility by mentioning un-archiving. It could add permission requirements or edge-case behavior, but this is adequate for a simple toggle.

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 long, front-loaded with the action, and every sentence adds value. There is no redundant or filler content.

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 2-parameter toggle tool with no output schema, the description covers the purpose, use case, and non-destructive nature. It lacks mention of permission requirements or behavior when the course is already in the requested state, but given the tool's simplicity, the provided context is sufficient for an agent to use it correctly.

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

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

The schema already documents the 'visible' parameter with 'false = archive/hide, true = unarchive/show', and the description mostly restates that. The 'course_id' parameter has no schema description and is not explained in the description, relying on the name for inference. With 50% schema description coverage, the description does not significantly compensate for the missing course_id semantics, so a baseline score 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 clearly states the tool's function: 'Archive (visible=0) or un-archive (visible=1) a course.' It uses specific verbs and identifies the resource, distinguishing it from similar operations like delete_resource or hide_section. The two modes are explicitly defined.

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 explicit use cases: 'Use it for end-of-year cleanup or hiding a course in preparation.' This tells the agent when to use the tool. However, it does not mention when not to use it or name alternative tools, so it falls short of a full 5.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the operation without mentioning side effects, error conditions, whether existing group memberships are preserved, or if the operation is atomic. This lack of transparency is a significant gap for a mutation tool.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It efficiently communicates the core action without redundancy.

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

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

For a tool with two simple parameters and no output schema, the description covers the basic action but omits important context such as the need for existing groups/users, expected behavior on duplicates, and error handling. Given the lack of annotations, additional context would improve completeness.

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 description mentions 'group_id' and 'users' which map to the schema's group_id and user_ids parameters, but it does not explicitly use the parameter names or add meaningful detail about their format or constraints. With 0% schema description coverage, the description should compensate more by explaining the relationship and potential requirements.

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 the specific verb 'Add' and clearly identifies the resource ('users') and target ('a group by group_id'). This distinguishes it from sibling tools such as create_group, which focuses on creating groups rather than adding users to existing ones.

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

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

The description clearly conveys the tool's purpose: associating one or more users with a specific group. It implies use when the group already exists and users need to be added, but it does not explicitly mention alternatives or exclusions, such as not using it when creating a new group.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that previous roles are not unassigned and explains Moodle's multi-role-per-context behavior, which is critical for a mutation tool. It could be improved by mentioning permissions or failure modes, but the key side effect is clearly 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?

The description is two sentences with no filler. The first sentence states the action and allowed roles; the second adds the critical caveat. Information is front-loaded, and 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 tool with 4 parameters and no output schema, the description covers the main action and a crucial behavioral nuance, but it omits aspects like permission requirements, expected return value, and the v0.5 course-level-only limitation (which appears only in the schema description). It is adequate but not fully comprehensive.

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

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

The schema description coverage is only 25%, so the description needs to compensate. It adds meaning for new_role by enumerating the accepted values and clarifies context_level as 'course-level'. However, it does not explain user_id or course_id beyond their names, which are intuitive but not explicitly defined. The description partially bridges the schema 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?

The description uses a specific verb ('Assign') and resource ('course-level role to a user'), and explicitly lists the supported roles. It clearly distinguishes the tool from sibling tools like enrol_csv by focusing on role assignment rather than enrolment. The added note about not unassigning previous roles further sharpens its purpose.

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 to use the tool by noting that it does NOT unassign previous roles, indicating a use case where retaining existing roles is important. However, it does not explicitly state alternatives or contrast with sibling tools like enrol_csv or unenrol_student, so the guidance is mostly implied rather than 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals idempotency, defaults (hidden, unlimited attempts, grade=10, method=highest), and internal slug-to-ID resolution for section_num. However, it does not clarify whether an existing quiz is updated via merge (keeping unspecified fields) or by resetting to defaults, leaving a notable ambiguity for an upsert operation.

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

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

The description is four sentences, each carrying distinct value: purpose, idempotency + defaults, internal resolution, and usage workflow. It is front-loaded, concise, and contains no filler or repetition of schema 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?

Given the complexity of a 12-parameter tool with no output schema and no annotations, the description gives a strong high-level overview and workflow, but it lacks details on update behavior (merge vs. overwrite), return values, and prerequisites like permissions. These gaps could confuse an agent when invoking the tool for updates or edge cases.

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 only 17%, so the description must compensate. It explicitly maps defaults for visible (hidden), attempts (unlimited/0), grade (10), grademethod (highest), and explains that section_num is resolved by the plugin. The remaining parameters (timeopen, timeclose, timelimit_seconds) are not mentioned, but their names are reasonably self-explanatory, and the description adds significant meaning for the most critical ones.

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 'Create or update a quiz shell (no questions)' — a specific verb, resource, and a clear exclusion of question content. It distinguishes this tool from siblings like import_gift and get_quiz_questions by explicitly stating it handles the quiz shell only and pointing to publish_exam_lesson for combined functionality.

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 explicit usage guidance: 'Combine with import_gift to populate questions, or use publish_exam_lesson for both in one call.' It also states idempotency by slug, signaling it can be used for both creation and updates. This clearly tells the agent when to use this tool versus 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?

With no annotations, the description carries full burden. It discloses two important behaviors: 'Propagates visibility to all modules inside the section' (side effect) and 'Idempotent' (repeatability). This goes beyond the basic action, though it does not mention prerequisites like whether the section must already be in preview state or potential 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?

The description is three concise sentences, each contributing unique information: the core action, the propagation effect, and idempotency. It is front-loaded with the most important information and contains no filler or repetition.

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

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

The tool is relatively simple, but the description omits guidance on parameter usage (especially resource_ids) and does not distinguish it from similar publish tools. It does cover the essential behavior and side effects, but for a tool with no annotations and no output schema, more context is needed to be fully complete.

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 compensate. It mentions 'section' which maps to section_id, but does not explain course_id or resource_ids at all. The optional resource_ids parameter could be used to restrict propagation, but the description says 'all modules' without addressing this ambiguity. The description adds minimal value over the bare 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?

The description clearly states a specific action: 'Make a previewed section visible to students.' It specifies the resource (section) and the effect (visible to students), and adds propagation to all modules, which distinguishes it from broader publish tools. This is a strong verb+resource statement.

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 usage context is implied: this tool is used when you have a previewed section and want to make it visible. However, it does not explicitly state when to use this tool over sibling tools like publish_preview or release_section, and no alternatives or exclusions are mentioned.

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

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

With no annotations provided, the description carries the full burden. It discloses the default eventtype, the recurrence behavior when repeat_count > 0, and the return value (event id and metadata). However, it does not mention potential side effects, prerequisites, or error conditions, leaving some behavioral aspects opaque.

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

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

The description is concise and front-loaded with the purpose. Every sentence provides useful information: the action, the default, the recurrence option, and the return value. There is no wasted wording.

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 tool with 9 parameters and no output schema, the description gives essential behavior and return information but omits details about parameter interactions, prerequisites, and potential failure modes. It is adequate but leaves gaps that the schema cannot fully fill.

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

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

The schema description coverage is only 44%, leaving many parameters (name, groupid, location, description, eventtype) without explanations. The description adds little beyond what the schema already states: it repeats the default for eventtype and the recurrence semantics for repeat_count, without clarifying the other parameters.

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

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

The description clearly identifies the action ('Create') and the resource ('calendar event'), distinguishing it from sibling tools like update_event and delete_event. It also provides key defaults and recurrence behavior, making the tool's purpose unambiguous.

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

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

The description establishes clear context that this tool is for creating events, and the mention of default eventtype and recurrence helps guide when to use it. However, it does not explicitly name alternative tools for other operations, so it falls short of a 5.

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

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

With no annotations, the description carries the burden. It discloses the MOODLE_WS_COURSE_EXISTS error for duplicate idnumbers and states default visibility, format, and section count. Most defaults already appear in the schema, and it omits other behavioral details like permissions or side effects.

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 concise sentences, front-loaded with the primary purpose, then error behavior and defaults. There is no filler; 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?

For a 9-parameter creation tool with no output schema and no annotations, the description is too thin. It omits return value, permission requirements, and guidance for required fields, making it insufficient for an agent to invoke confidently without further schema inspection.

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 only 22% (lang and idnumber_slug have descriptions). The description adds little beyond the schema: it mentions 'stable idnumber' and defaults but does not explain fullname, shortname, categoryid, summary, or numsections semantics, leaving a significant 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?

The description opens with 'Create a new Moodle course', using a specific verb and resource, and adds 'with a stable idnumber' to define scope. This clearly distinguishes it from sibling tools like update_course and duplicate_course.

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 'Create a new' clearly signals use for new course creation, and the idnumber uniqueness error implies create-vs-update context. However, it does not explicitly name alternatives like update_course or state when not to use the tool, so it misses a 5.

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

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

With no annotations, the description carries the full burden. It discloses key behaviors: 'Idempotent by slug' (upsert behavior), default hidden and general type, and the requirement of a plugin companion. While it does not detail update semantics (e.g., merge vs replace) or return values, it provides meaningful behavioral context beyond the schema.

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

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

The description is three concise sentences, each adding value: purpose, idempotency, defaults, and a dependency. It is front-loaded and free of fluff, making it easy for an agent to parse quickly.

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

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

Despite the description's clarity, the tool has 7 parameters, no output schema, and no annotations, so it needs more completeness. It covers core behavior but omits important context such as how updates affect existing data, what the plugin companion is for, and how to choose between this tool and create_forum_announcement. These gaps make it merely 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 only 43%, meaning the description must compensate. It adds meaning for 'slug' via idempotency and clarifies defaults ('hidden forum of type general') which are already present in the schema. It does not explain the roles of course_id, name, intro, or visible beyond what is implicit, leaving significant parameter ambiguity.

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

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

The description clearly states 'Create or update a forum' with the resource being a forum in a course section, and it mentions idempotency by slug. However, it does not explicitly distinguish itself from the sibling tool 'create_forum_announcement', despite mentioning announcements as a forum type, 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?

The description provides clear context: it is for creating or updating forums in a course section, and idempotency by slug implies use when you have a stable slug. However, it lacks explicit when-not-to-use guidance or alternatives, especially given the existence of create_forum_announcement.

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

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

The description discloses only the default forum behavior when forum_id is omitted, but this is already captured in the schema's forum_id description. It omits the schema's additional fallback to the first forum, and it does not mention permissions, side effects, return values, or any other behavioral traits. With no annotations, the description carries the full burden and falls short.

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 extremely concise, using two short sentences to convey the core action and a key default. It is front-loaded with the primary purpose and contains no irrelevant 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?

Given that this is a create operation with six parameters, no annotations, and no output schema, the description is incomplete. It does not explain the required fields (subject, message, course_id), any permission prerequisites, or what the tool returns upon success. It only partially covers the forum_id behavior, leaving significant context gaps for an AI agent.

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 description adds little meaning beyond the schema. It does not explain the purpose of subject, message, pin, or format, and the only parameter it touches (forum_id) restates (and slightly understates) the schema's own description. With schema coverage at only 17%, the description fails to compensate for the missing parameter documentation.

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

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

The description clearly states the action ('Post a new discussion') and the resource ('course forum'), making it immediately distinct from sibling tools like create_forum (which creates a new forum) and send_moodle_message (which sends a message). The specific verb and object leave no ambiguity about what this tool does.

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

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

The description provides a practical hint about the default forum when forum_id is omitted, which implies a common use case (posting to Announcements). However, it does not explicitly state when to use this tool over alternatives like create_forum, send_moodle_message, or other communication tools, nor are there exclusion criteria.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It only states the core action and one follow-up step, but omits details about side effects, permissions, response shape, or nuances like idnumber auto-generation or idempotency. This is a significant gap for a mutation tool.

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

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

The description is extremely compact and front-loaded: a single sentence with clear subject and action, plus a brief directional pointer. Every word earns its place, and there is no redundant 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?

Given the lack of annotations and output schema, plus four parameters, the description is too thin. It does not convey prerequisites, return values, error conditions, or the lifecycle of the created group beyond the hint to assign members later. This leaves the agent with insufficient context 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 description coverage is only 25% (one property documented), and the description does not compensate. It does not explain the meaning of course_id, name, idnumber, or description beyond what is minimally implied by 'group'. The lone hint to 'populate it after' is about workflow, not parameter semantics.

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

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

The description clearly states the action ('Create') and the target resource ('a group inside a course'), which is specific and distinguishes it from sibling tools like assign_to_group, create_section, or create_course. The phrase 'inside a course' adds necessary scoping.

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 explicit context by directing the agent to use assign_to_group afterwards to populate the group, which clarifies the intended workflow and distinguishes this tool from its sibling. However, it does not mention when not to use this tool or alternative approaches beyond the one next step.

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

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

With no annotations, the description carries the burden for behavioral disclosure. It usefully discloses idempotency by name, but does not mention what happens on success (return value), permission requirements, or error conditions. This leaves notable gaps beyond the idempotency 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 clear, front-loaded sentences with no redundancy. The action verb and resource are stated immediately, and the idempotency note is a bonus 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?

For a create operation with 5 parameters and no output schema or annotations, the description is adequate but incomplete. It explains creation and idempotency, but does not specify return values, failure modes, or permission requirements. Given the tool's moderate complexity, more context would be helpful.

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 only 20% (only position has a description). The description lists the key parameters (name, summary, position, visibility) and clarifies name behavior via idempotency, but course_id and defaults are left to the schema. It adds some meaning but does not fully compensate for the low coverage.

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?

Clearly states 'Create a new section in a course' and lists the specific attributes (name, summary, position, visibility), making the tool's function unambiguous. The idempotency note further distinguishes it from sibling tools like update_section or duplicate_section.

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 it clear this is for creating new sections, which implies when to use it. It provides a key usage nuance (reusing a name returns existing section), but does not explicitly mention alternatives or exclusions. This is clear context without explicit when-not-to-use 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the delete_repeats option, which clarifies default behavior, but it does not mention whether deletion is permanent, if special permissions are required, or what happens to related attendee data. This is a significant gap for a destructive operation.

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

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

Two concise sentences with a front-loaded purpose statement and a clear instruction. No unnecessary words, making it easy to parse quickly.

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 2-parameter tool with no output schema or annotations, the description covers the core function and the key option. However, it lacks important context such as permanence of deletion, permission requirements, or behavior for events that have already occurred, leaving some gaps.

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

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

The schema only describes delete_repeats, not event_ids. The description adds value by clarifying that event_ids refer to calendar events, partially compensating for the gap. However, it does not add semantics beyond what the schema already provides for delete_repeats, so the contribution is moderate.

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

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

The description clearly states the verb 'Delete' and resource 'calendar events', distinguishing it from sibling tools like update_event or create_calendar_event. It also specifies that multiple events can be deleted at once and mentions the delete_repeats option, making the scope explicit.

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

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

The description provides clear context for when to use this tool: whenever you need to delete calendar events. It also gives a specific instruction for handling repeat instances (set delete_repeats=true), but does not explicitly reference alternative tools or exclusions. This is clear context without exclusions, aligning with the 4-level.

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

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

With no annotations, the description carries the full burden. It discloses the default mcp: prefix safety check, the force bypass, and the noop return for non-existent modules. These are key behavioral traits that go beyond the schema and help the agent predict outcomes. It does not mention permanence or permissions, but the safety guard is well conveyed.

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 concise sentences that front-load the purpose and then provide key details. Every word earns its place, with no redundancy or filler.

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

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

Given the tool's simplicity (3 params, no output schema), the description is complete enough. It explains the core action, the safety default, the force option, and the noop edge case. It could mention permissions or what 'course module' entails, but for the complexity level, it suffices.

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 67%, so the description adds some meaning beyond the schema. It reinforces the idnumber semantics by tying it to the mcp: prefix and get_course_context, and explains the force parameter's effect. course_id remains undocumented in both schema and description, but it is a standard identifier. Overall, the description compensates well for most gaps.

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

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

The description clearly states the action: 'Delete a Moodle course module by idnumber.' This is a specific verb+resource+identifier construction that distinguishes it from sibling tools like delete_event. The additional detail about MCP-managed idnumbers further clarifies its scope.

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

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

The description provides clear context on when to use the tool, noting the default safety behavior and when to use force=true. It does not explicitly mention alternatives, but it references get_course_context for finding idnumbers, giving practical guidance. No exclusions are given, but the context is clear enough for a simple delete 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value by revealing that cloning uses backup+restore internally and that the new course is hidden by default. However, it does not mention permissions, whether the source course is affected, or if the operation is asynchronous, so it is not fully comprehensive.

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 three concise sentences that immediately state the main purpose, then provide meaningful default behavior details. There is no redundant or filler content, and the structure front-loads the most important 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 tool is moderately complex with a nested options object and seven parameters, but the description only covers core behavior and defaults. It omits how to customize options (e.g., including users), expected return values, and any prerequisites. With no output schema or annotations, this is a notable gap, though the schema and defaults partially compensate.

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 description does not address any parameters directly, and the schema description coverage is 0%, meaning the description fails to compensate for the lack of explanation. Although the schema itself has rich property descriptions, the tool description adds no parameter semantics, which is a significant gap for a tool with 7 parameters.

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 starts with 'Clone a course into a new one' which is a specific verb+resource that clearly distinguishes this tool from siblings like create_course or duplicate_section. It also adds context about implementation (backup+restore) and default behavior, leaving no ambiguity about its function.

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 useful context about what is copied by default (activities/blocks/filters) and what is not (users/enrolments/grades), helping the agent understand the tool's typical use. It does not explicitly name alternatives or state when not to use it, but the context is clear enough to guide 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It adds valuable context beyond the schema by noting the operation is idempotent and returns 'exists' when the section name already exists. However, it does not disclose other important traits such as whether the operation is destructive to existing data, what happens on invalid input, or what return value is expected on success.

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 immediately states the primary action and key exception. It is front-loaded with the verb and resource, and every sentence carries meaningful information without unnecessary detail.

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?

As a mutation tool with no output schema, the description should clarify what the caller receives on success and how the input parameters affect behavior. It mentions the 'exists' idempotent case but not the success return value (e.g., new section ID) or the effect of the 'visible' parameter. This leaves important gaps for an agent to invoke the tool correctly and interpret results.

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 50%, so the description should compensate for undocumented properties like course_id and visible. It does not: it only restates that the new section name comes from the 'name' parameter, which the schema already says. The phrase 'use get_course_context to find section IDs' is already in the schema and adds no new meaning. The description fails to clarify the remaining half of the parameters.

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 the specific verb 'duplicate' and clearly identifies the resource: 'all modules from a source section into a new section in the same course.' This distinguishes it from siblings like create_section or duplicate_course, and the scope (same course) is explicitly 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?

The description provides clear context for when to use the tool: to duplicate all modules from a source section into a new section. It doesn't explicitly list alternatives or exclusions, but the purpose is unambiguous enough for an agent to select it over other section-related tools. The parameter description for source_section_id adds helpful prerequisite guidance by pointing to get_course_context.

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

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

With no annotations, the description must carry the behavioral burden. It discloses two key traits: 'Creates missing users by default with a random temp password' and 'Returns per-row status'. This covers the main side effect and result format. However, it does not mention permission requirements, whether existing users' roles are updated, or how errors in the CSV are handled. It provides moderate transparency but not full disclosure for a mutation operation.

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

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

The description is exactly two sentences, front-loaded with the primary action and input format, followed by key behavioral notes. Every sentence adds essential information without redundant wording. It is concise and well-structured.

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 tool's complexity (4 parameters, no output schema, no annotations), the description covers the essential aspects: CSV format, user-creation behavior, and per-row status. It does not explain the detailed content of the status return or any permission/prerequisite requirements, but it provides enough for an agent to understand the tool's core purpose and side effects. It is reasonably complete for a batch operation.

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 50%: csv_content and create_users_if_missing have descriptions, while course_id and default_role_shortname do not. The description adds the CSV column layout and optional role, which supplements csv_content. It also confirms the default user-creation behavior. However, it does not explain course_id semantics or how default_role_shortname interacts with the optional role column in the CSV, leaving some parameters under-described.

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

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

The description clearly states the tool's function: 'Batch-enrol users in a course from a CSV'. It specifies the resource (course users), the action (enrol), and the input format (CSV with email, firstname, lastname, and optional role). This distinguishes it from sibling tools like unenrol_student or list_students, making its purpose unambiguous.

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

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

The description provides clear context that this tool is for batch enrollment via CSV, implying it should be used when multiple users need to be enrolled at once. However, it does not explicitly name alternatives or provide when-not-to-use guidance, such as pointing to change_role for individual role changes. The usage context is clear, but exclusions are 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?

With no annotations, the description must disclose behavioral traits itself. It mentions the required environment variable, the return shape ({ cmid, video_url, page_url }), and the asynchronous-ish wait time (~1 minute). It also implies a write operation by 'embed it in a new mod_page'. It could add side effects like cost or idempotency (which schema hints at), but the provided context is above average for a mutation tool.

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

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

The description is two sentences, front-loaded with the primary action, and every clause adds value: the resource (mod_page), the model (Veo 3.1), the language requirement, the dependency (API key), the return value, and the time estimate. No filler or repetition of schema content.

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 complex 11-parameter tool with no output schema, the description provides essential operational context: return format (not in schema), time-to-completion, and prerequisite. It could mention deletion or failure modes, but given the high schema coverage and the concise description, it is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 91%, so the description doesn't need to explain parameters. The description adds no extra parameter details beyond what the schema already provides (e.g., prompt must be Italian, idnumber for idempotency). Baseline 3 is appropriate because the schema handles parameter semantics, and the description doesn't need to compensate.

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

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

The description opens with a specific verb+resource ('Generate a short Italian-language video with Google Veo 3.1 and embed it in a new mod_page in Moodle'), clearly distinguishing it from the sibling tools, which are course management, quiz, and messaging tools. It unambiguously states what the tool does and its primary side effect (creating a mod_page).

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

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

The description provides clear context for when to use the tool: for Italian-language short videos, with a stated prerequisite (GEMINI_API_KEY) and performance expectation (~1 minute). It does not explicitly name alternative tools or exclusion scenarios, but no sibling tool serves the same purpose, so the context is sufficient. A slight deduction for lacking explicit 'when not to use' 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?

With no annotations, the description carries the full burden. It discloses the default status filter and the optional per-user grading status, which adds useful context. However, it does not describe the return format, whether it modifies data (though 'get' implies read-only), or any access requirements. This leaves gaps for the 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?

The description is a single, front-loaded sentence that conveys the core purpose and a key option. It contains no redundant information and is appropriately 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?

For a read tool with 4 parameters, no output schema, and no annotations, this description is minimally sufficient. It covers the main behavioral options but omits details about the response structure and the relationship between user_ids and include_status_per_user (though the schema covers that). The absence of output schema raises the need for more description, which is not fully met.

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 75% (3 of 4 parameters have descriptions). The description adds the default 'submitted' and the notion of per-user grading status, which aligns with include_status_per_user. It does not significantly extend beyond the schema, which already documents assign_id, user_ids, and include_status_per_user.

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

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

The description clearly states it retrieves submissions for an assignment, with a default status filter of 'submitted'. The name 'get_assign_submissions' reinforces this. The optional per-user grading status is also mentioned, adding scope without ambiguity.

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 for fetching assignment submissions but does not explicitly state when to use this tool versus alternatives. No alternatives or exclusions are mentioned. The context of sibling tools (e.g., get_grades, get_completion) makes the purpose clear, but the guidance is implicit rather than 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?

With no annotations present, the description carries the burden of behavioral disclosure. It usefully enumerates the possible state values and mentions the completion timestamp, but it does not explicitly state that this is a read-only operation, nor does it cover permissions, pagination, or error 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?

The description is a single compact sentence with no wasted words. It is concise, but it is a grammatical fragment lacking a verb and omits the connection between 'per cmid' and the input parameters, making it under-specified despite its brevity.

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 getter, the description adequately covers the return content—per-cmid state and timestamp—especially given the absence of an output schema. However, it does not explain what cmid refers to, whether the result is a list or single object, or how the two required parameters influence the result. It is adequate but leaves several contextual gaps.

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 should compensate by explaining course_id and user_id. It only paraphrases them conceptually and introduces 'cmid' as an output grouping without clarifying that cmid is not an input parameter. No additional meaning is added beyond the parameter names.

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 identifies a specific resource—activity completion status for a user in a course—and distinguishes it from sibling tools like get_grades by listing per-cmid state values and timestamp. However, it lacks an explicit action verb such as 'Gets' or 'Returns,' reading more as a noun phrase than a full tool statement.

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 is provided on when to use this tool versus alternatives like get_grades or get_course_logs. It does not mention typical use cases, prerequisites, or situations where another tool would be more appropriate.

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

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

No annotations are provided, so the description carries the full burden. It discloses the content of the returned 'radiograph' and implies a read-only operation, but it does not mention potential side effects, limitations, or failure modes. It gives useful output detail but not exhaustive behavioral disclosure.

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 dense sentence enumerating return components, followed by a clear usage directive. Every word adds value, and the structure is well front-loaded with the primary purpose.

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 2-param tool with no output schema, the description covers the main return categories (metadata, sections, lessons, enrolments) and the invocation context. It lacks parameter explanations, but the core purpose and contents are sufficiently described for an agent to call it effectively.

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

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

The schema has 2 parameters but the description provides 0% coverage. It does not explain course_id or include_recent_lessons; the phrase 'recent MCP-published lessons' hints at the latter but no explicit mapping is made. The agent must infer parameter meanings from the output description, which is insufficient.

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?

Description uses a specific verb 'Returns' and a unique resource label 'compact radiograph of a Moodle course', enumerating concrete components (metadata, sections with module counts, recent MCP-published lessons, enrolment counts). This clearly distinguishes it from sibling tools like publish_class_lesson or get_course_logs.

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

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

The description explicitly instructs when to use it: 'Call this before publishing a lesson so the agent knows where it fits.' This provides clear context, though it does not mention exclusions or alternative tools for similar context needs.

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

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

With no annotations provided, the description carries the transparency burden. It discloses that the log is approximate, derived from enrollment data, and flags users within a time window. It does not explicitly state read-only behavior, but the nature of the tool implies it. The limitations are well communicated.

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 with no fluff. It front-loads the core purpose and efficiently covers the key behavioral detail (flagging window) and context (no generic WS). 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?

The tool is simple with 2 parameters and no output schema. The description explains the purpose, the approximate nature, the derivation source, and the time-window behavior. It hints at return values (per-user firstaccess/lastaccess) without detailing them, which is acceptable given no output schema. A small gap is not specifying the response format or error handling.

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 50%: hours_since has a description, course_id does not. The description reinforces the meaning of hours_since by explaining the 'last N hours' flagging, but adds little for course_id beyond its obvious role. It partially compensates for the missing course_id description but does not fully advance beyond schema details.

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

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

The description clearly states the tool's purpose: providing an approximate activity log for a course with per-user firstaccess/lastaccess data. It specifies the derivation source (core_enrol_get_enrolled_users) and the flagging behavior, distinguishing it from siblings like get_grades or get_completion.

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 context by noting that Moodle core does not expose a generic activity-log WS, suggesting this is the workaround. However, it does not explicitly state when to use this tool over alternatives or provide exclusion criteria.

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

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

With no annotations provided, the description bears the transparency burden. It discloses the return payload (raw/max grade, item name, module type, feedback) and the behavior when user_id is omitted (returns for all enrolled users). It does not mention errors, permissions, or side effects, but the 'Get' verb and return-focused wording imply a non-mutating operation.

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

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

The description is a single, compact sentence that front-loads the action and scope, then lists the return fields. Every word adds value; no filler or repetition.

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

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

The tool has no output schema, but the description compensates by specifying the returned fields. The optional user_id behavior is clearly explained. It omits potential error conditions or prerequisite permissions, but for a simple read operation with only two parameters, the description provides adequate context.

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

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

The schema already describes the user_id parameter's optional behavior (50% coverage). The description adds no new parameter-specific information beyond repeating that user_id is optional and indicating course context. The course_id parameter remains undocumented in the schema and description, though its meaning is easily inferred from the tool's purpose.

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 ('Get') and resource ('gradebook entries'), clearly stating the optional scope (a single user or all enrolled users if user_id is omitted). It also lists the returned data (raw/max grade, item name, module type, feedback), which distinguishes it from siblings like get_quiz_attempts or get_completion.

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 (when to retrieve grades, optionally for all users), but it does not explicitly contrast with alternative tools or mention situations where this tool should not be used. The guidance is implicit rather than 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?

With no annotations, the description carries the transparency burden but largely mirrors schema details: the default status is already in the schema, and include_review's heavier nature is also described in the schema. It adds minimal new context beyond confirming read-only behavior via the tool name.

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 short sentences that front-load the core purpose and essential usage note, with no wasted 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?

The description covers the main purpose, default behavior, and a critical performance caveat, which is sufficient for a retrieval tool. It omits details like status enum values and return format, but these are available in the schema.

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

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

The schema has only 25% coverage (include_review). The description compensates by clarifying that quiz_id and user_id target a specific user on a quiz, and it explains the status default and include_review behavior, making the tool usable without reading 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?

The description clearly identifies the resource (quiz attempts), the scope (a user on a given quiz), and implies the 'get' action via the tool name. It distinguishes from siblings like get_quiz_questions (questions) and get_grades (grades) by focusing specifically on attempts.

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 explains the default behavior (finished attempts) and when to use include_review for per-question details, noting the heavier cost. However, it does not explicitly reference alternative tools or mention when not to use this 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?

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly states 'Read-only' and discloses the return shape (question id, name, type, slot number), which is meaningful behavioral context. It doesn't cover error cases or pagination, but for a simple list operation this is adequate.

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

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

The description is two concise sentences, front-loaded with the primary action, and contains no filler. Every word adds value: it names the resource, the identification mechanism, the read-only nature, and the return 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?

Given the low complexity of a list operation, no output schema, and no annotations, the description is nearly complete: it states the purpose, the key identifier, and the returned fields. It could mention the role of course_id or behavior when the quiz doesn't exist, but these are minor gaps.

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 50%, with only the slug parameter described. The description reinforces slug's role as the quiz identifier, but it adds no meaning for course_id, leaving the agent to infer its purpose. This is acceptable because course_id is likely obvious from course context, but not fully compensated.

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 a clear resource ('all questions attached to a quiz'), and immediately distinguishes this from sibling tools like modify_question and import_gift by focusing on retrieval. The phrase 'identified by its slug' further pins down the exact scope.

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

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

The description clearly frames when to use the tool: when you need a read-only list of a quiz's questions. It doesn't explicitly name alternatives or state when not to use it, but the read-only declaration and contrast with mutation/modification siblings imply the appropriate context.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses that including functions can return a large list (though the schema already says this) and positions the call as a bootstrap verification step. However, it does not explicitly state that it's a read-only safe operation or describe the response structure beyond 'site + user + token info', leaving some behavioral expectations unspecified.

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, front-loaded with the main purpose, and includes a specific, useful tip. No filler or repetition of schema content. It earns its place efficiently.

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 diagnostic tool with two optional parameters and no output schema, the description conveys the core purpose and a key use case. It could be more complete by summarizing what 'site + user + token info' includes or warning about the large response size (though the schema does warn), but it's largely sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the parameters are well-documented. The description reinforces the use of include_functions=true in a bootstrap context, adding a practical semantics beyond the schema's technical description. However, it does not add new information about functions_filter. Thus it stays at the baseline of 3.

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

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

The description clearly states the tool retrieves site, user, and token info, and names the underlying web service function. It distinguishes itself from sibling tools by emphasizing token and function list verification, making its purpose specific and unambiguous.

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

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

It provides a concrete usage scenario: 'Use include_functions=true at bootstrap to verify which plugin WS functions are exposed to the token.' This implies when the tool is useful but does not explicitly mention alternatives or when not to use it. There is clear context, just no 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?

No annotations are provided, so the description carries the full disclosure burden. It does mention useful behaviors (HTML-safe feedback, team grading support, workflow state) but fails to state that this saves/overwrites an existing grade, whether the change is reversible, or what the response looks like. For a mutation tool, this is a significant transparency 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?

The description is three short sentences, front-loaded with the core purpose, and every sentence adds information (operation, HTML-safety, team/workflow features). No redundant or filler content.

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 7 parameters, no annotations, and no output schema. The description covers some advanced features (team grading, workflow) but omits critical context such as return values, error behavior, permission prerequisites, and the fact that existing grades will be overwritten. Given the tool's complexity, the description is minimally adequate but incomplete.

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 descriptions cover 57% of parameters. The description adds modest meaning by noting feedback text is HTML-safe and mentions team/workflow capabilities, but it does not clarify the three undocumented parameters (assign_id, user_id, feedback_text) beyond what their names suggest. The added context is helpful but not comprehensive enough to raise the score above baseline.

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

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

The description clearly states the action ('Manually grade') and the resource ('an assignment submission'), and references the underlying Moodle function (mod_assign_save_grade) to remove ambiguity. There are no sibling tools that perform grading, so it is well-differentiated.

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 the tool is for manual, human-mediated grading but does not explicitly state when to use it versus alternatives (e.g., bulk/automatic grading tools) or provide any exclusion criteria. No other grading tool appears among siblings, but the guidance is still implicit rather than 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?

The description discloses an important behavioral trait: visibility propagates to all modules inside the section. With no annotations provided, the description carries the full burden, but it does not mention reversibility, permissions, or other side effects. This is a moderate level of transparency – useful but not comprehensive.

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 concise sentences. The first sentence states the primary action and target, and the second sentence adds a key propagation detail. Every word earns its place, with no fluff or unnecessary repetition.

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

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

For a simple mutation tool with two parameters and no output schema, the description covers the core action and the important propagation behavior. It does not mention reversibility or response format, but these are not strictly necessary given the tool's simplicity and the absence of an output schema.

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

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

The schema defines two parameters (course_id and section_id) with clear, self-descriptive names and integer types. However, schema_description_coverage is 0%, and the description does not explicitly explain or elaborate on these parameters. The parameter names are intuitive enough, so the lack of additional semantics is acceptable but not fully compensated.

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?

Description uses the specific verb 'Hide' with the resource 'course section' and audience 'from students', and clarifies that visibility propagates to all modules inside the section. This clearly distinguishes it from sibling tools like release_section, which makes the purpose unambiguous.

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

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

The description implies the use case: use this tool when you want to hide a course section from students. However, it does not explicitly mention alternatives, such as using release_section to unhide, or any exclusions or prerequisites. Guidance is adequate but not 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?

With no annotations, the description carries the full burden and discloses important traits: it creates questions in a bank category, appends to quiz slots by default, and is idempotent with deduplication by question name. This provides useful behavioral context beyond a simple import statement, though it does not specify whether existing questions are updated or skipped.

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 three sentences that front-load the primary purpose, then add the key behavioral details (default append and idempotency). Every sentence adds value with no wasted 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?

The description covers the core behavior and default option, and the schema fills in most parameter details. Missing are explicit return values or error behavior, but for an import tool with no output schema, the current information is likely sufficient 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 descriptions cover 4 of 5 parameters (80%), leaving only course_id without a description. The description mentions the bank category and quiz slots but does not add meaningful syntax or interplay details beyond what the schema already states for append and category_name.

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+resource ('Import GIFT-formatted questions into a quiz') and adds context about creating questions in a bank category and appending them to quiz slots. This clearly distinguishes it from sibling tools like modify_question or get_quiz_questions.

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 the use case for importing GIFT text into a quiz but does not explicitly state when to use it over alternatives or provide exclusions. No contrast with tools like configure_quiz or modify_question is given, making the guidance implied rather than 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?

No annotations are provided, so the description carries the full burden. It states the basic operation and optional filters, but does not disclose what events are returned (e.g., default behavior with no filters, pagination, return format), permissions required, or any other behavioral traits. This is a significant gap for a tool with no output 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 that avoids redundancy. Every word contributes to explaining the purpose and key options, with no filler or repetition.

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

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

The tool has five optional parameters and no output schema, yet the description only covers the core listing and filtering behavior. It omits return value details, pagination, default scope, and any usage prerequisites. For a tool with this complexity and no annotations, the description is underspecified.

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

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

The schema has no parameter descriptions (0% coverage), so the description's mention of 'courses/groups/categories' and 'timestart/timeend range' adds meaning to all five parameters. It clarifies their purpose as filters, but does not explain how they combine or whether both timestart and timeend are needed together. These are reasonable basics but not comprehensive.

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

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

The description clearly states the verb 'List' and the resource 'calendar events', and specifies the filtering dimensions (courses/groups/categories, timestart/timeend). This distinguishes it from sibling tools like create_calendar_event, update_event, and delete_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?

The description implies when to use the tool (to list calendar events) but does not explicitly say when not to use it or compare to alternatives. It provides context about optional filters, which implies usage for retrieval, but no direct exclusions or alternatives are mentioned.

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

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

No annotations are provided, so the description must stand alone. It states what the tool does but does not disclose behaviors like whether hidden courses are included by default (only_visible defaults to false in the schema), pagination, or rate limits. The schema provides some parameter details, but the description itself is minimal and does not add behavioral 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?

The description is a single sentence with no wasted words. It front-loads the purpose and includes a useful parenthetical, making it both concise and well-structured.

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

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

The description is sufficient for a simple listing tool, but it lacks details on return structure, pagination, and the meaning of limit. Since there is no output schema and annotations are absent, the description could be more informative to fully guide an agent.

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 description adds a note on userid sources ('obtain from get_site_info for the bot, or pass a student_id-mapped Moodle userid'), which supplements the schema's userid description. However, it does not explain the limit parameter at all, and only_visible is already described in the schema. With schema coverage at 67%, the description provides partial added value.

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

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

The description clearly states the tool's function: 'List courses where a user is enrolled.' The verb 'list' and resource 'courses' are specific, and the scope (for a given userid) distinguishes it from sibling tools like list_students or get_course_context.

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 on when to use the tool by specifying it lists courses for a specific user, and provides a useful hint on obtaining the userid from get_site_info. It doesn't explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

With no annotations provided, the description carries the transparency burden. It reveals the output fields (id, fullname, email, lastaccess, roles, groups) and the default role (student), which helps the agent understand the operation's behavior. However, it does not explicitly state that this is a read-only operation or detail limit-related behavior, though those are partially covered by 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 two sentences, front-loaded with the core purpose, and contains no filler. Every sentence adds useful information: the action, the filter, and the return fields.

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

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

For a simple list tool with no output schema, the description covers return fields and default behavior, which is sufficient for basic usage. It does not mention pagination or maximum results, but the schema includes a limit parameter with default and maximum, leaving only minor gaps.

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

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

The schema has 0% description coverage, so the description must add meaning to parameters. It explains that 'role' is a role shortname and notes the default, adding semantic value beyond the enum. However, it does not mention the 'limit' parameter or elaborate on 'course_id', so the compensation is only partial.

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

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

The description clearly states the tool's function: 'List enrolled users in a course.' It specifies the primary resource (course users), the verb (list), and adds detail about filtering by role and return fields. This distinguishes it from sibling tools like list_my_courses or get_grades.

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 to use it (when you need enrolled users in a course and optional role filtering), but it does not explicitly mention alternatives or exclusions. It lacks guidance on when to prefer other tools like enrol_csv or change_role, so the usage context is only implied.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses read-only behavior and the deferral of awarding, but omits details about return format, error handling, visibility rules, or authentication requirements.

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; first sentence states purpose and optional filtering, second conveys read-only constraint. No wasted 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?

For a simple two-parameter list operation, the description gives the essential purpose and a read-only caveat. It doesn't specify return structure, but 'List' implies an array of badge records; this is acceptable given the tool's low 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?

The schema documents course_id as an optional filter, and the description reinforces it, while user_id has no schema description but is clarified by 'earned by a user.' It doesn't fully compensate for the missing semantics of user_id (e.g., whether it is a Moodle user ID or requires a specific role).

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?

Description uses specific verb 'List' and clear resource 'badges earned by a user,' distinct from sibling tools like list_students or get_grades. Optional course_id filter further clarifies scope.

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?

States read-only and explicitly notes awarding badges is deferred to v0.6, which sets the expectation that this tool is for querying, not modifying. It doesn't name an alternative for awarding because none exists among siblings, but it clearly implies when not to use this 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?

With no annotations, the description carries the transparency burden. It discloses that the tool writes directly to the DB and bypasses a specific Moodle bug, which is valuable behavioral context. It also enumerates the editable fields. However, it does not mention permissions, reversibility, or return behavior, leaving some significant gaps.

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

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

The description is concise and well-structured: it opens with the core purpose, follows with a key behavioral note, and then summarizes inputs. Every sentence adds value without unnecessary verbosity.

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 does not need to explain return values, but it could have mentioned likely return behavior. It covers purpose, usage context, behavioral trait (DB write, bug bypass), and parameter summary. For a focused edit tool, this is sufficient, though it omits permission requirements and side effects.

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 high (80%), so the baseline is 3. The description adds a high-level summary of inputs and coverage (name, text, answers) but largely repeats what the schema already documents. It clarifies that fields are optional and can be skipped, but that info is already present in the schema descriptions.

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

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

The description clearly states the tool's purpose: editing an existing question, with specific examples (typo fix, reformulation, feedback tweak). It uses a specific verb and resource, distinguishing it from other tools in the sibling list such as import_gift or configure_quiz.

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

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

The description provides clear context: for editing questions, and mentions bypassing a known Moodle form bug, which implies when this direct-DB approach is needed. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of a full 5.

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

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

With no annotations, the description carries the behavioral burden. It discloses idempotency ('republishing the same lesson updates in place, never duplicates') and the default mode ('hidden'), which are valuable. However, it does not mention permissions, effects on existing section content, or what happens when section_id is omitted, leaving gaps.

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, front-loaded with the core action, and each sentence adds distinct value (purpose, idempotency, default, and alternative workflow). No wasted 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?

Given the tool's complexity (publishing to Moodle with optional section_id) and lack of output schema, the description covers key aspects but omits return behavior, prerequisites, and distinction from publish_exam_lesson. It is adequate but not fully complete for a tool with no annotations or output schema.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It only indirectly references lesson_path ('LessonPlan markdown file') and repeats the mode default already present in the schema. It does not explain course_id or section_id semantics or the distinction between optional and required fields.

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 action ('Publish a LessonPlan markdown file as a Moodle section with component modules'), clearly identifying the resource and result. It also differentiates from the preview workflow by naming publish_preview and confirm_preview, making the tool's purpose distinct among siblings.

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

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

The description explicitly directs users to the preview workflow ('Use publish_preview + confirm_preview for the preview workflow'), providing a clear alternative. It also notes the default mode is 'hidden', which is practical guidance for typical use.

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

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

No annotations are provided, so the description carries the full burden. It discloses idempotency by (course_id, slug) and mentions that repair+promote steps are run, making the quiz immediately attemptable. These are meaningful behavioral facts beyond the schema, though details on return values or error handling are absent.

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 three sentences long, starts with the primary purpose, and includes no redundant or filler content. Every sentence earns its place, making it highly concise and well-structured.

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 complexity of 14 parameters, no output schema, and no annotations, the description is too brief. It covers the core action and key behaviors but leaves out return-value semantics, error handling, and the meaning of several parameters, making it incomplete for effective agent use.

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 only 29% (4 of 14 params have descriptions). The description mentions course_id and slug for idempotency and gift_text for questions, but it does not clarify many other parameters like grademethod, section_num, or timelimit_seconds. With such low coverage, the description insufficiently compensates.

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

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

The description clearly states a create-or-update operation for a quiz populated with GIFT questions, distinguishing it from sibling tools like import_gift or configure_quiz. The mention of 'in one call' additionally highlights its combined nature, making the purpose unambiguous.

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

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

The description implies usage as a combined create/update + import operation, but it does not explicitly contrast with alternatives such as import_gift when a quiz already exists. There is no when-not guidance or mention of preferred scenarios, leaving some ambiguity.

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

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

With no annotations, the description carries the burden. It discloses the hidden preview state, that students will not see anything until confirm_preview, and the return shape (same as publish_class_lesson plus preview_url). This provides meaningful behavioral context, though it omits details like permission requirements or whether the preview is overwritable.

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. The second sentence adds essential behavior (hidden from students) and return shape. No wasted 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?

For a simple two-parameter tool, the description covers the key context: the preview workflow and what to expect in the response. It references publish_class_lesson for extended return details, which helps completeness, but lacks any error/side-effect information.

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 description does not explain what lesson_path or course_id represent or how they are used. The parameter names are somewhat self-explanatory, but the description adds no additional semantic value.

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 action: 'Publish a LessonPlan in hidden preview mode.' It clearly identifies the resource (LessonPlan) and the mode (hidden preview), and differentiates from siblings by referencing publish_class_lesson and confirm_preview.

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 the intended workflow: use this to create a preview, then call confirm_preview to make it visible. It references publish_class_lesson for shape comparison, but doesn't explicitly state when to prefer this over other publishing 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?

No annotations are provided, so the description must carry the full burden. It states the primary effect but omits important behavioral details such as required permissions, idempotency (what happens if the section is already visible), reversibility (though implied by hide_section), or side effects on students or sub-sections. This is a significant gap for a mutation tool.

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

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

The description is a single concise sentence that immediately communicates the action and its relationship to hide_section. Every word contributes value, with no filler or redundant 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 tool with no output schema or annotations, the description is quite sparse. It does not mention what the tool returns (e.g., success response), prerequisites (section must exist, user permissions), or edge cases (already visible, invalid IDs). Given the simplicity of the tool, more behavioral context is expected.

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 compensate. While the parameter names course_id and section_id are largely self-explanatory, the description adds minimal semantic meaning beyond what names provide. It implicitly links them via 'course section' but doesn't clarify valid values or relationships, so a 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 uses a specific verb 'Make' and clearly identifies the resource 'course section visible to students'. It also explicitly names the reverse operation 'hide_section', which distinguishes it from the sibling tool and clarifies its role.

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

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

The description provides clear context by stating it is the reverse of hide_section, implying when to use it (when a section should be made visible). However, it does not explicitly enumerate when-not-to-use scenarios or alternatives beyond hide_section, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses that the operation is batched and deterministic, but it does not mention potential side effects (e.g., unlisted sections shifting), permissions, or reversibility. The schema provides more detail but the description itself remains vague.

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 with no filler, front-loading the primary action. Every word serves a purpose, making it highly concise and well-structured.

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 mutation tool with no annotations and no output schema, the description is incomplete. It does not mention return values, error behavior, or the effect on sections not listed in the array (only hinted at in the schema). The tool's complexity is moderate, but the description underspecifies essential context.

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

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

Schema description coverage is 50%, and the description does not compensate. It repeats the array structure but adds no meaning beyond the schema's existing order description. The course_id parameter is entirely unexplained, and the description omits details like 0-indexing or behavior for omitted sections (both present only in 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?

The description clearly identifies the action (reorder) and the resource (sections in a course), distinguishing it from sibling section tools like create_section, update_section, or hide_section. The mention of a batched call reinforces its specific purpose.

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 it is for bulk reordering ('in one batched call') but does not explicitly state when to use this tool over alternatives, nor does it name any alternative. It gives no negative guidance 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?

With no annotations provided, the description carries the behavioral transparency burden. It discloses the key behavior of generating and returning a password when omitted, and emphasizes the out-of-band delivery requirement. However, it does not mention potential side effects like invalidating existing sessions or what happens on failure.

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, front-loaded with the primary action, and contains no fluff. Every sentence adds critical information: the core purpose and the optional-password behavior with a security instruction.

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

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

The description covers the main usage scenario and the special case of omitted new_password, but it lacks important context for a mutation tool, such as whether the reset takes immediate effect, side effects like logging out existing sessions, or behavior on invalid user IDs. This is partially mitigated by the schema's details on new_password.

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

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

The schema covers one of two parameters (new_password) with a detailed description, but user_id lacks any description. The tool description does not add meaning for user_id beyond the tool name's implication, and it merely repeats the new_password behavior already described in the schema. With only 50% schema coverage, the description should compensate but does not.

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

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

The description clearly states the tool resets a user's password, with a specific verb and resource. It also distinguishes behavior based on the optional new_password parameter, making the purpose unambiguous.

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

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

The description gives clear context on when to use the tool (to reset a password) and includes an important guideline: if no new_password is provided, the generated password must be forwarded to the user out-of-band. It does not explicitly mention alternatives, but no sibling tool offers similar functionality.

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 description mentions a recipient limit and the underlying Moodle function, but since there are no annotations, it carries full burden for behavioral disclosure. It does not explicitly note that this is a write operation with side effects, nor does it cover authentication, failure modes, or response format, leaving significant gaps.

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 concise sentence that front-loads the core action and includes a key constraint. It contains no fluff or redundant phrasing, making it highly efficient for an agent to parse.

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 small parameter set and lack of output schema, the description is somewhat complete but omits important context such as return values, error handling, and behavior with invalid user IDs. The absence of annotations increases the need for such details, which are not provided.

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 only 33%, and the description does not compensate for the lack of detail on 'text' and 'format'. The max-50 recipient limit is repeated from the schema without adding new meaning. The description adds no significant semantic value beyond what the parameter names and enum already 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?

The description clearly states a specific action ('Send a private Moodle message') and identifies the target ('one or more user ids'), which distinguishes it from sibling tools like create_forum_announcement. It also includes a concrete constraint ('Max 50 recipients per call'), making the tool's function 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 implies usage for private messaging but does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions. It lacks references to sibling tools or scenarios where a different communication method would be more appropriate.

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

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

No annotations are provided, so the description carries the full burden. It adds valuable context by stating 'Non-destructive: user data is preserved, only the course enrolment link is removed', which goes beyond the schema. However, it omits details about permissions, return values, and edge cases like unenrolling non-enrolled users.

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 sentence that is front-loaded with the core action. Every clause earns its place, with no redundant or vague wording.

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

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

The description is adequate for a simple two-parameter tool, covering purpose and safety. However, it lacks parameter-level detail and usage alternatives, leaving some ambiguity for an agent selecting or invoking the 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 compensate. It only maps 'one or more users' and 'course' to user_ids and course_id, but does not explain the semantics of the IDs, accepted formats, or behavior when parameters are invalid.

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

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

The description clearly states the verb 'Unenrol' and the resource 'one or more users from a course', making the tool's purpose unambiguous. This also distinguishes it from sibling tools like enrol_csv and change_role.

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 guidance on when to use this tool versus alternatives, such as enrol_csv for enrolling users. The description only states the operation and non-destructive nature, but does not provide exclusions or context for 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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only says 'Update' and notes a required-field constraint; it does not mention permissions, reversibility, side effects, or what happens if no fields are provided. This is insufficient for a mutation tool.

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

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

The description is a single concise sentence with no filler. The action verb and resource are front-loaded, and the field list is compact.

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 annotations and no output schema, the description must provide comprehensive context. It fails to clarify update semantics, return values, error behavior, prerequisites, or authorization requirements. The enumerated fields and one constraint are not enough for a 7-parameter mutation 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 compensate. It lists field names already present in the schema, adding only the 'at least one field required' constraint. It does not explain valid values for lang, visible, or categoryid, nor the role of course_id beyond being required.

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

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

The description clearly states the tool updates a course and enumerates the specific updatable fields (fullname, shortname, summary, visible, lang, categoryid). This distinguishes it from sibling tools like update_section or create_course.

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 this tool is for modifying existing course fields, but it does not explicitly state when to use it over alternatives or provide exclusion criteria. No mention of create_course, update_section, or conditions where a different tool should be used.

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

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

With no annotations provided, the description carries the full burden. It discloses the tool's limited scope (only changes timestart) and warns that full event updates are unavailable, which is key behavioral context. However, it does not mention permissions, return values, or side effects on existing event details, which would have strengthened transparency further.

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 focused sentences, with the primary action front-loaded. The second sentence efficiently conveys the limitation and alternative without redundancy, making every word count.

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 mutation tool, the description covers the core behavior, its limitation, and the recommended alternative for other changes. No output schema exists, but the tool's purpose is fully explained, making it complete for an agent to decide when and how to invoke 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 coverage is 50% (only new_timestart has a description). The description implies the role of event_id (which event) and new_timestart (the new time), but it adds little beyond what the schema already states. It does not elaborate on event_id's format or any constraints 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?

The description clearly states the tool reschedules a calendar event to a new timestart, using a specific verb and resource. It also distinguishes itself from siblings by explicitly noting that other changes (name, description, location) are not supported, setting it apart from create/delete event tools.

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

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

The description explicitly says when to use this tool (to reschedule) and when not to (to change name/description/location), providing the alternative of delete + re-create. This is a clear usage guideline with an explicit exclusion, referencing the Moodle WS limitation.

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

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

No annotations are provided, so the description carries the full burden. It discloses a key side-effect—visibility propagates to all modules inside the section—and a validation rule (at least one field required). However, it does not mention permission requirements, reversibility, or return values, which are important for an update operation.

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

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

The description is two concise sentences that front-load the primary action and include a critical behavioral note. No unnecessary words or repetition of schema details.

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 moderately simple, but without an output schema, the description should clarify what the agent can expect after a successful update or on errors. It covers the core behavior and the propagation side-effect, but omits return/error handling and permission context, leaving some ambiguity for a well-rounded decision.

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 lists the updatable fields and adds the rule that at least one of them is required, which is not present in the schema. It does not describe course_id and section_id in detail, but those are self-explanatory from the context.

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

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

The description clearly states the tool's function: updating a course section with specific fields (name, summary, visible) and identifies the resource by section_id. This distinguishes it from sibling tools like create_section, hide_section, and reorder_sections, which have different operations.

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 for updating section metadata but does not explicitly compare with alternative tools such as hide_section or release_section. It provides clear context (update by section_id and course_id) but lacks explicit exclusions or alternative recommendations, leaving potential ambiguity around the 'visible' field versus dedicated hide/release 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?

With no annotations provided, the description carries the transparency burden. It discloses the return shape: 'Returns `{ data }` on success, structured `meta.code` + `isError: true` on failure,' giving agents a concrete expectation of both success and error behavior. The 'escape hatch' metaphor additionally signals that this tool bypasses typical facades, though it does not detail potential side effects or validation 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?

The description is composed of two tightly crafted sentences. The first front-loads the core purpose, and the second packs in return format and usage guidance. There is no filler or repetition of schema details.

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 generic escape-hatch tool, the description covers the essentials: what it does, when to prefer alternatives, and the shape of success/failure responses. It could also warn that function calls are not validated and may have destructive effects, but the 'escape hatch' label and the nudge toward high-level facades partially cover 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?

Schema description coverage is 0%, so the description must compensate by explaining parameter meaning. It only says 'with arbitrary parameters,' which essentially repeats the free-form nature of the `params` object already visible in the schema. It does not explicitly state that `params` are passed directly to the Moodle function or how they map to function arguments, leaving a significant gap for a tool that is inherently parameter-driven.

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 'Escape hatch: call any Moodle Web Services function with arbitrary parameters,' which clearly and specifically identifies the tool's purpose and scope. This distinguishes it from high-level sibling tools that each target a single Moodle operation, positioning ws_raw as a generic passthrough.

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 closing sentence, 'Prefer high-level facades when they cover your use case,' gives explicit guidance on when to use this tool versus the alternatives. It also labels the tool an 'escape hatch,' which implies it should be a fallback option, not the first choice.

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