learnworlds

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

Annotations only declare destructiveHint=true, so the description's 'may enroll them in the group's products' adds real behavioral context about the side effect of this write. It stops short of describing reversibility, permissions, or idempotency.

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

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

Two tight sentences: the WRITE label and core action are front-loaded, and the endpoint reference is a compact optional detail. No padding.

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

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

For a two-parameter write tool with no output schema, the description covers the mutation nature and its side effect adequately. It omits error behavior (e.g., what happens if the user is already in the group) and any permission requirements, but nothing essential to invoking it is missing.

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

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

Schema description coverage is 100% with only two parameters, so the schema already documents group_id (with a pointer to list_user_groups) and user. The description adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('add an existing user to a user group') and even cites the underlying endpoint. It doesn't explicitly distinguish itself from the sibling learnworlds_enroll_user, which is the closest competing action, so it falls short of a 5.

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

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

The word 'existing' implies the user must already be created (use learnworlds_create_user otherwise), which is useful implied guidance. However there is no explicit when-to-use/when-not statement or named alternative, leaving the enroll_user vs add-to-group choice to inference.

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

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

Annotations only supply destructiveHint=true, so the description adds meaningful disclosure: no password or admin flag are accepted by design, and the registration-email flow governs how the account becomes usable. It omits auth scope and duplicate-email behavior, but for a small write tool this is solid added 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?

Three compact clauses with the write marker front-loaded and zero filler; every sentence carries operational 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 7-parameter write with no output schema and a nested 'fields' object, the description plus the fully documented schema covers enough to invoke correctly. It lacks guidance on duplicate emails or required-field failure modes, which keeps it from a 5.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns more by explaining the intent behind send_registration_email (it substitutes for a password field), which the schema's 'Send LearnWorlds' registration email' does not convey.

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

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

States a specific verb+resource ('create a learner account') and immediately scopes it with 'WRITE' and the LearnWorlds endpoint. The 'no password or admin flag' clause implicitly distinguishes it from any admin-provisioning sibling and from update_user, so an agent can route correctly.

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

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

It gives a real usage instruction — set send_registration_email so the learner sets their own password — but offers no when-to-use vs. when-not guidance and never names an alternative sibling such as update_user or add_user_to_group. Implied usage only.

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 adds real behavioral context beyond the destructiveHint annotation: it grants access, records a manual enrollment at a given price, explicitly does NOT charge the learner's card, and optionally emails the learner. It omits auth/permission needs and idempotency (behavior when the user is already enrolled), so it is strong but not complete.

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

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

Two compact sentences, front-loaded with the 'WRITE:' signal and the operation, followed by the behavioral caveats and endpoint. No filler.

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

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

For an 8-parameter mutation tool with no output schema and only a destructiveHint annotation, the description covers the essential behaviors an agent needs (access grant, price recording, no charging, optional email). It lacks any statement about already-enrolled behavior or response shape, keeping it from a 5.

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 88%, so the schema already documents nearly every parameter. The description reinforces price semantics ('use 0 for a free grant') and the no-charge rule, but adds little else beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific verb+resource with the exact scope: 'manually enroll a user in a course, bundle or subscription'. The 'WRITE:' prefix and manual-enrollment framing clearly separate it from read siblings like get_user_course_progress or list_user_courses, and from learnworlds_add_user_to_group.

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

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

Gives clear context for when this is the right tool (manual enrollment, no card charge, 'use 0 for a free grant') and implies the learner-facing purchase path is different. It does not name a sibling alternative or state an explicit when-not, 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds nothing beyond that: no note on error behavior for a missing slug, no auth requirements, and no return shape. The endpoint reference (GET /v2/courses/{id}) is a minor signal but largely restates the read-only nature already annotated.

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 terse sentences with the operation front-loaded and no padding. The trailing API endpoint reference is mildly redundant but costs almost nothing.

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

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

For a single-parameter, read-only lookup with its safety profile carried by annotations and its parameter documented by the schema, this is largely sufficient. The one modest gap is that with no output schema, nothing hints at what a course object contains.

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

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

Schema description coverage is 100% with a single required parameter, so the schema already documents that course_id is the slug with an example. The description's 'by id (its slug)' is redundant with that, so it earns no credit above the baseline.

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

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

States a specific verb (Fetch) and resource (one course) and singles out the singular scope by id/slug, which naturally separates it from learnworlds_list_courses. It does not name a competing sibling explicitly, but the scope is unambiguous.

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

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

Usage is only implied: the agent can infer this is the single-record lookup versus the list tool, but there is no explicit when-to-use or when-not-to-use guidance, and no mention of how it relates to learnworlds_get_course_contents or learnworlds_get_course_analytics.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is established and the bar is lower. The description adds the return-content scope (which metric families are included) and the underlying endpoint, but says nothing about permissions, aggregation window, or whether values are per-course or cumulative.

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

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

Two compact clauses with zero waste: the metric summary is front-loaded and the endpoint reference trails as supporting detail. Nothing is repeated or padded.

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

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

For a one-parameter read-only analytics tool with annotations covering safety, the description is nearly sufficient, and its metric enumeration partially substitutes for the absent output schema. Missing only framing details such as the reporting period or aggregation scope.

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?

Single required parameter with 100% schema description coverage — the schema already documents that course_id is the slug. The description adds no parameter-level detail beyond the schema, so the baseline 3 holds.

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

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

States a specific verb+resource (course analytics) and enumerates the metric categories returned — students, learning units, average score, study time, social interactions, certificates — which visibly separates it from siblings like get_course_grades (per-student grades) or get_course. It does not name those alternatives, but the metric list makes the distinct purpose clear.

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 explicit when-to-use guidance, no conditions, and no routing to alternatives such as get_course_grades or get_user_course_progress. The metric list hints at the use case but the agent is left to infer when this tool is appropriate versus its siblings.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read. The description adds useful scope detail — that it enumerates sections, drip-feed settings, and activity types with ids — but says nothing about response size, pagination, or ordering, which matters for a nested content tree.

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

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

A single, front-loaded sentence that names the resource and enumerates its contents, followed by a compact endpoint reference. Efficient, with only the API route arguably redundant given structured metadata elsewhere.

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

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

With no output schema, the description must convey return shape, and it does reasonably well by enumerating sections, activities, and ids. It omits any note on nesting depth or volume, but for a straightforward read tool this is largely sufficient.

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

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

Schema description coverage is 100% and the single course_id parameter is fully documented there, including the slug format example. The description adds nothing beyond the schema regarding parameters, so the baseline 3 applies.

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

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

States the specific resource returned — the course outline with sections (drip-feed settings) and learning activities (videos, PDFs, SCORM, assessments, certificates) plus their ids. This clearly distinguishes it from siblings like learnworlds_get_course (metadata) or learnworlds_get_course_analytics (metrics), though it never explicitly names those alternatives.

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

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

Usage is implied: call this to retrieve a course's structural outline. There is no explicit when-to-use vs when-not guidance and no mention of which sibling to prefer for a lighter-weight course fetch, leaving the agent to infer the boundary from sibling names.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the description only needs to add context. It usefully discloses the shape of the returned data (per user, per learning unit, submission time) but says nothing about pagination behavior despite page/items_per_page parameters, or about result volume.

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

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

A single front-loaded sentence that describes the payload followed by a short endpoint reference; nothing is padded. The trailing 'LearnWorlds: GET /v2/courses/{id}/grades' line earns little for an agent but costs almost no space.

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 7-parameter read tool with no output schema and minimal annotations, the description covers the resource but omits pagination, filtering semantics, and any indication of result size or format. Adequate to select the tool, thinner than ideal for calling it precisely.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema and the baseline of 3 applies. The description adds no syntax or format detail beyond what the schema supplies, though it indirectly hints at learning-unit filtering by naming the units concept.

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

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

States a specific verb and resource ('Assessment grades of the users enrolled in a course') plus the granularity of the data ('per user and learning unit, with submission time'), which differentiates it from generic progress tools like learnworlds_get_user_course_progress. It does not, however, explicitly name the sibling it replaces or when this differs from course progress/analytics, so it stops short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance, no prerequisites, and no mention of alternatives such as learnworlds_get_course_analytics or learnworlds_get_user_course_progress. The agent must infer relevance purely from the resource noun.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It contributes the underlying REST endpoint (GET /v2/payments/{id}), which is marginal, and says nothing about 404 behavior, auth scope, or whether a missing id returns an error.

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, zero filler, with the core action and its lookup keys front-loaded before the endpoint reference. Nothing could be trimmed without losing information.

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

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

For a single-resource getter the description is functional but thin: with no output schema, it gives no hint of what a payment record contains, and it is silent on the failure case (unknown id / bad key). Adequate, not 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 coverage is 100% and the schema description already states 'The payment id or the transaction id.' The description repeats this dual-key behavior rather than adding format, prefix, or resolution-order details, so baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one payment') plus the accepted lookup keys (payment id or transaction id), which implicitly separates it from list_payments. It stops short of naming the sibling explicitly, but the singular scope is unambiguous.

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

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

The mention of 'by payment id or transaction id' implies the precondition for calling it, but there is no explicit when-to-use guidance, no when-not, and no pointer to list_payments as the alternative for browsing.

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

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

readOnlyHint=true already declares the safe-read profile, and the description adds genuine value by enumerating the returned fields despite there being no output schema, plus the underlying endpoint. It does not explain what happens when the user is not found or the effect of include_suspended.

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

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

One front-loaded sentence naming the resource, key modes and payload, plus a short endpoint reference. 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 read tool with annotations covering safety and no output schema, listing the returned fields is exactly the compensating detail needed. Only the suspended-user behavior is left unaddressed, and that is covered by 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?

Schema coverage is 100%, so baseline is 3. The description reinforces that 'user' accepts either an id or an email, but says nothing about include_suspended, adding little 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?

Specific verb (Fetch) + resource (one user) + identifier modes (id or email), and it enumerates the returned payload (profile, role, tags, sign-up fields, UTMs, last login). This clearly distinguishes it from learnworlds_list_users and learnworlds_get_user_course_progress.

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?

Implies single-user lookup keyed by id or email, which is enough context to pick it over list_users, but it never states when to prefer it over siblings like get_user_course_progress or when-not (e.g., bulk lookups). No explicit alternatives are named.

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

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

Annotations declare readOnlyHint=true, so the safety profile is already covered and the description does not need to restate that. Instead it adds genuinely useful behavioral context: the exact set of returned metrics (progress rate, average score, time on course, completed units, per-section/per-activity breakdown), which is valuable because there is no output schema. It does not mention pagination, permissions, or error behavior, keeping it out of 5 territory.

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

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

A single compact sentence front-loads the core deliverable (progress in one course) and appends the raw API endpoint for precise mapping. There is no filler or repetition, though the endpoint reference is metadata rather than agent-facing guidance.

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

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

With no output schema, the description steps in to enumerate the returned fields, which is exactly the gap it needed to fill for a two-parameter read tool. Combined with readOnlyHint covering safety, an agent has enough to call it correctly, though nothing is said about auth requirements or identifier fallback behavior.

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

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

Schema description coverage is 100% — both 'user' (id or email) and 'course_id' (slug, e.g. "my-first-course") are fully documented in the schema, including that different identifier formats are accepted. The description adds no parameter-level detail beyond this, so the baseline of 3 is correct.

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

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

The description names the exact resource (a single user's progress in one course) and enumerates the payload it covers: status, progress rate, average score, time on course, completed units, and a per-section/per-activity breakdown. This is far more specific than a tautology and lets an agent distinguish it from aggregate tools like learnworlds_get_course_analytics or learnworlds_get_course_grades. It stops short of explicitly naming the sibling it is not, so a 5 is not warranted.

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 statement of when to use this tool versus alternatives such as learnworlds_get_course_grades, learnworlds_list_user_courses, or learnworlds_get_course_analytics. The endpoint mapping (GET /v2/users/{id}/courses/{cid}/progress) implies the single-user, single-course scope, but no exclusion or routing guidance is given. A reader must infer all usage conditions.

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

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

Annotations declare readOnlyHint=true, and the description usefully supplements that with the page size (20 per page) and sort order (newest first), which matter for pagination behavior. It doesn't discuss rate limits or total-count behavior, keeping it just under 5.

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

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

One dense sentence that front-loads sort order, page size, and filters, then states the required-parameter rule and the API endpoint. No filler.

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

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

For a read-only list tool with no output schema, the description covers filtering, ordering, pagination size, and the endpoint. It omits what a certificate record contains and how to page through results (e.g. stop conditions), which is a minor residual gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine semantic constraint not expressed in the schema: the course_id/user_id mutual requirement. It also clarifies the filter combination is conjunctive in spirit ('and/or').

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

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

States a specific verb and resource ('Certificates awarded ... for a course and/or a user') and adds scope detail (newest first, 20 per page) plus the backing endpoint. An agent can immediately distinguish it from siblings like list_course_users or get_user_course_progress.

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

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

Gives an explicit precondition — 'at least one of course_id or user_id is required' — which is a real routing rule since the schema marks zero parameters required. It doesn't name alternative tools for adjacent questions (e.g. per-user course progress), so it stops short of 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely new behavior: newest-first ordering, 50-per-page pagination, and the fact that it doubles as a cheap connectivity/credential check. It does not mention total counts or whether further pages exist, but it goes well beyond the annotation.

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

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

Two sentences, zero filler. The listing scope, ordering, page size, and returned fields are front-loaded, with the credential-check tip and the underlying endpoint following compactly.

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 filterable read-only list tool with no output schema, the description supplies ordering, page size, returned field set, one useful use case, and the backing endpoint. Combined with annotations and a fully documented schema, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so all three parameters (page, access, categories) are already documented with their semantics. The description repeats access values (paid/free/draft) and mentions filtering by categories, adding little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the school's courses') and immediately enumerates the returned fields (title, price, access, categories, author). The plural 'List' plus the school-wide scope cleanly distinguishes it from the singular learnworlds_get_course and from user-scoped siblings like learnworlds_list_user_courses.

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

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

Gives a concrete use case, 'a cheap way to confirm the credentials work,' which tells the agent when this is a good low-cost call. No explicit when-not or named alternative (e.g., use get_course for a single course), so it stops short of full routing guidance.

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

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

Annotations declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavior — default page size of 20 and 'newest first' ordering — which an agent needs to reason about pagination and result order. It stops short of describing total counts or response shape.

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

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

Two sentences, no filler; the resource and ordering are front-loaded before the endpoint citation.

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

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

For a read-only, three-parameter list tool with full schema coverage and annotations covering safety, the description supplies what is missing (defaults, sort order). Only the absence of any return-shape hint keeps it from a 5, and no output schema exists to 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 coverage is 100%, so the baseline is 3; the description adds the default items-per-page value (20) that the schema's 1-200 range does not state, giving marginally more than the schema alone.

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

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

States the exact resource (users enrolled in one course) and a distinguishing scope, so an agent can tell it apart from list_users and list_user_courses without reading the schema. Also cites the underlying endpoint, anchoring semantics.

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

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

Usage is implied by the resource phrasing (listing enrollees of a single course), but there is no explicit when-to-use/when-not-to-use guidance and no alternative named for the adjacent list_users / list_user_courses siblings.

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

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

readOnlyHint already tells the agent this is a safe read. The description adds useful non-schema context: pagination size (50 per page) and the scope of logged activities. It stops short of auth, rate-limit, or default-ordering behavior, which the schema's sort default partly covers.

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

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

One front-loaded sentence that leads with the resource and page size, then filters, then the API mapping. The long event-type enumeration slightly overlaps the activity enum, keeping it just shy of a 5.

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

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

For a read-only, 100%-documented-schema list tool with no output schema, the description supplies page size and content scope. Return-value structure would be nice but the schema coverage and readOnly hint leave no critical gap for correct invocation.

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

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

Schema coverage is 100% with enums fully described, so the schema carries parameter meaning. The description only summarizes the filter axes (user, activity, time) without adding syntax beyond the schema's Unix-timestamp and enum 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?

States a specific verb+resource ('The school's activity log') and enumerates the concrete event types it returns, which no sibling (users, courses, payments, certificates) covers. An agent can immediately tell this is the event-stream tool.

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

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

Implies usage via 'filterable by user, activity and time,' giving the agent a sense of when the tool applies, but names no alternative or when-not condition relative to siblings like list_payments or list_users.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: default page size (50), sort order (newest first), and the shape of what is returned. No auth or rate-limit details, but it goes meaningfully past the annotations.

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

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

Purpose and behavior are front-loaded in a single dense sentence, followed by two short fragments. Every clause carries information; the only minor cost is that the field list is a long appositive run rather than being split out.

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 correctly compensates by enumerating the returned fields. With 0 required params and full filter documentation in the schema, an agent has what it needs to call this correctly; only cross-tool routing guidance is thin.

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

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

Schema coverage is 88%, so the schema does most of the work, but the description adds two things not in the schema: the ANDed filter semantics and the default 50-per-page behavior (the schema's items_per_page states no default). This is above the baseline-3 case where the schema carries everything.

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

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

States a specific verb+resource ('List payments') and immediately enriches it with sort order (newest first), default page size, and the fields returned (product, price, discount, tax, coupon, affiliate, gateway, billing). This distinguishes it cleanly from the singular sibling learnworlds_get_payment.

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

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

Provides a composition rule ('All filters are ANDed') which is genuine usage guidance for combining the 8 optional filters. However, it never names when to use this versus learnworlds_get_payment, nor any exclusions or prerequisites, so routing relies on inference from the list/get naming.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds pagination behavior (50 per page) and the underlying endpoint, but says nothing about ordering, empty results, or pagination termination.

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

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

A single tight sentence that front-loads the resource and return fields, followed by the endpoint reference. No filler, though the endpoint restatement is marginal value for an agent.

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

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

No output schema exists, and the description compensates by naming the key returned fields (enrollment and expiry dates) and the page size. It is nearly sufficient for a simple two-parameter read tool, missing only ordering/pagination-termination detail.

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

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

Schema description coverage is 100%, so both parameters (user id-or-email, page) are already fully documented in the schema. The description adds no parameter detail, which is acceptable at this coverage level.

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

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

States a specific verb+resource: the courses a user is enrolled in, with the returned fields (enrollment and expiry dates). This distinguishes it from the inverse sibling list_course_users (users in a course) and from get_user_course_progress, though it never names those alternatives.

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

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

No when-to-use guidance or routing against siblings such as learnworlds_get_user_course_progress or learnworlds_list_course_users. The agent must infer the use case from the purpose statement alone.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds real value beyond them by disclosing the sort order ('newest first') and the returned attributes (title, products, group managers, capacity, tags). It does not mention pagination behavior despite the page parameter, which is the main residual gap.

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

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

A single front-loaded sentence covering purpose, scope, sort order, returned fields, and the underlying endpoint, 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?

For a read-only list tool with no output schema, the description covers what is returned and in what order, which is what an agent needs. The only omission is pagination guidance for the page parameter, which is minor here.

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

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

There is one parameter (page) with 100% schema description coverage, so the schema already explains its semantics. The description adds nothing about paging limits or defaults, so it neither compensates nor detracts - baseline 3.

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

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

States a specific verb (List) and resource (the school's user groups), and clarifies the domain jargon with '(cohorts / B2B seats)' plus the API endpoint GET /v2/user_groups. This clearly separates it from siblings like learnworlds_list_users and learnworlds_list_course_users.

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

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

Usage is only implied by the verb - an agent can infer this is the way to enumerate groups, but the description never states when to prefer it over learnworlds_list_users or learnworlds_list_course_users, nor any prerequisites. No explicit when/when-not guidance is given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context on top: default sort order (newest first), default page size (20), and the important semantic that all filters are ANDed together. It omits rate limits and total-count behavior, hence 4 rather than 5.

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

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

Two tight sentences, front-loaded with the operation and ordering, followed by filter semantics and the API mapping. Zero filler.

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

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

For a 9-parameter read-only list tool with no output schema, the description covers ordering, default page size, filter composition, and endpoint. The main gap is that response shape and pagination metadata are undocumented in both the description and any output schema, but the essentials for correct invocation are present.

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

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

Schema description coverage is 78%, so the baseline is 3. The description adds two things not in the schema: the default of 20 items per page (schema only gives the 1-200 range) and the AND semantics for combining filters, which materially changes how an agent composes a query.

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

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

Specific verb+resource+scope: 'List the school's users, newest first (20 per page by default)'. It also enumerates the filterable dimensions, which cleanly separates it from learnworlds_get_user (single user) and learnworlds_list_course_users (course-scoped) without opening either schema.

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

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

Usage is implied by the filter list and the pagination default, but the description never states when to prefer this over siblings like learnworlds_list_course_users or learnworlds_get_user, nor any prerequisites. Adequate but no explicit routing guidance.

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

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

Goes beyond destructiveHint=true by disclosing PATCH semantics ('only the fields you pass are sent') and the destructive nature of the tags parameter (REPLACES the tag list). It does not cover auth/permission requirements or side effects of changing email/username, so not a full 5.

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

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

Front-loaded WRITE prefix, then scope, then the critical caveat, then the alternative. Three compact sentences with no filler.

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

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

For a destructive mutation with no output schema, the key facts an agent needs (partial-update behavior, tag replacement risk, sibling alternative) are present. Missing only permission/authorization notes and the effect of identifier (email/id) changes.

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%, and the description compensates by enumerating the mutable fields and clarifying the tags parameter's replace-not-append semantics, which the schema label only partly conveys. It still omits format hints for email/username beyond what the schema implies.

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

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

States a specific verb and resource ('update a user') plus the exact mutable fields, and prefixes with WRITE. It also distinguishes itself from the sibling it resembles (learnworlds_update_user_tags) by name.

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

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

Explicitly routes the agent: for adding/removing individual tags use learnworlds_update_user_tags instead. It also tells the agent that only passed fields are sent, giving clear context for when to use this tool versus the tags helper.

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

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

Annotations only supply destructiveHint=true, so the description usefully adds that other tags are preserved, that the operation is reversible via the opposite action, and that it maps to PUT /v2/users/{id}/tags. It does not cover edge behavior such as adding a duplicate tag or detaching a tag the user lacks, so it stops short of 5.

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

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

Two tight sentences with a front-loaded 'WRITE:' marker, the core semantics, the side-effect guarantee, and the API endpoint. No filler and nothing buried.

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

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

For a 3-required-param mutation with no output schema, the description covers the write nature, reversibility, and side-effect scope, which is most of what an agent needs. Remaining gaps (duplicate-tag handling, error behavior on unknown tags) are minor for this 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 67%: 'user' and 'tags' are documented in-schema, but 'action' has only an enum with no description. The description compensates by mapping attach/detach to add/remove, giving meaning the schema alone lacks. The scoping note ('other tags untouched') further clarifies the 'tags' parameter's effect.

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

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

States a specific verb+resource ('add (attach) or remove (detach) tags on a user') and scopes it precisely with 'leaving their other tags untouched'. An agent can distinguish this from sibling learnworlds_update_user, which handles other user fields, without opening a schema.

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

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

The attach/detach framing tells the agent what the tool is for, but there is no explicit when-to-use guidance or naming of an alternative (e.g., using learnworlds_update_user for other user edits, or whether detach is preferred over a full replace). Usage is implied rather than stated.

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