LearnWorlds MCP

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.2
Disambiguation4/5
Most tools target a distinct resource+action pair, and the embedded HTTP paths in descriptions help disambiguate. However, a few reverse-relationship pairs (get_users_product vs get_products_user, get_user_segments vs get_users_segment) and mirror lookups (get_users_seat_offering vs get_seat_offerings_that_user_is_member) create real misselection risk despite clear descriptions.
Naming Consistency3/5
The dominant get_/create_/update_/delete_ + resource pattern is readable and mostly consistent. But deviations are frequent enough to dent coherence: get_list_subscription_plans, get_specific_seat_offering, deletes_user_group (grammar), update_certificate_reissue, delete_certificate_revoke_invalidate, add_invite_users_community_space, and review_submission_user_s_assessment_submission all break the convention.
Tool Count2/5
94 tools is far beyond the navigable range for an agent tool set, even accounting for the broad LMS domain. The volume forces massive tool lists and makes selection harder; this would be better split into multiple focused servers per domain (courses, users, commerce, community, etc.).
Completeness3/5
Coverage is deep for users, seats, user groups, and enrollments with full CRUD/membership operations. However, bundles and subscription plans are read-only, courses have create/get/update but no delete, community posts are read-only, and promotions lack update/delete — notable dead ends for lifecycle management across several core resources.
Average 4.7/5 across 91 of 94 tools scored. Lowest: 4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 4 commits in the last 12 weeks
- Last stable release on September 5, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by disclosing server-side auth injection, throttling under the 30-per-10s cap, retries on 429/5xx, return format (HTTP status plus JSON body), and detailed error mapping for 401/403/404/422. The inaccurate 'replaces the fields you send' statement for a suspend operation is a notable blemish, but the overall behavioral disclosure is rich and useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a method badge and purpose, then organized into labeled sections. However, it contains generic update-tool boilerplate ('replaces the fields you send', 'Read it first so you overwrite just the fields you mean to') that is irrelevant and potentially misleading for suspend_user, so not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a minimal schema and no output schema, the description covers the full call experience: endpoint, idempotency, auth, rate limiting, retry behavior, return payload, and error statuses. It also provides usage context and related tools. The mismatched 'replace fields' text is the main reason it is not a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers the only parameter (id) with a description ('User id or email (encoded string)'), so the baseline is 3. The tool description adds no further parameter-level meaning; it only restates the operation itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Suspends a user from loging in or creating another account.' This inherently differentiates it from the sibling unsuspend_user and other user-related tools. The additional update boilerplate adds some noise, but the core purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit 'Use when' condition ('only when the user asked to change an existing record'), advises reading the record first, and points to the create tool if the record doesn't exist. It also lists related Users tools. However, the 'overwrite just the fields you mean to' guidance is mismatched with suspend_user's single-id schema, making part of the guidance off-target.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description reveals server-side auth injection, LearnWorlds' 30-per-10s throttle with retries on 429/5xx, non-2xx error behavior, and specific status meanings (401/403/404/422). This is substantial operational disclosure, and it aligns with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The labeled sections (Behavior, Returns, Use when) make the content scannable, and almost every sentence adds useful info. Minor redundancy exists between 'Get analytics for a course' and 'Returns analytics about the course specified by the provided course id.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only lookup, the description is highly complete: it covers auth, throttling, retries, error semantics, and a use-case statement. With no output schema, the response body content is left generic ('LearnWorlds JSON response body'), but this is a minor gap for invocation purposes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter id is fully described in the schema ('Course Id'), and schema coverage is 100%. The description only repeats 'provided course id' without adding format, validation, or usage detail, so it adds no real value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific resource and operation: 'Get analytics for a course' via GET /v2/courses/{id}/analytics. It names related reporting tools but does not explicitly explain how this differs from get_analytics_learning_activity or the progress tools, so sibling differentiation is only partial.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use when: safe to call speculatively for lookups and reporting' provides clear context, and 'Not for changing anything — use the matching 🟡 write tool' gives an explicit exclusion. However, it only lists related reporting tools without specifying which scenario should select them instead of this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent/non-destructive, but the description adds meaningful behavior: creates/changes/deletes nothing, server-side auth injection, throttling under LearnWorlds' 30-per-10s cap, retries on 429/5xx, and detailed response and error semantics. This goes well beyond structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Information is well-organized under labeled sections and front-loaded with the endpoint and read-only marker. It is slightly redundant—the opening sentence repeats what 'Get upcoming affiliate payouts' already says and the behavior section reiterates read-only—but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool, it covers return format, failure modes, throttling, and use context. It stops short of describing the output body's shape or explicitly distinguishing upcoming from due/completed payouts, but those are minor gaps given the simple scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is already fully described in the schema ('Affiliate Id or email (encoded string)'), so the schema carries the burden. The description only restates that payouts are looked up by affiliate id and adds no encoding, format, or usage detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get upcoming affiliate payouts') and backs it with the exact GET endpoint. It is clear about the scope ('specified by the provided affiliate id'), but it does not explicitly differentiate upcoming from the sibling get_due_affiliate_payouts/get_completed_affiliate_payouts beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly labels 'Use when' and provides clear context: safe for speculative lookups and reporting, not for mutations, with a pointer to a write tool. It lists related affiliate tools but doesn't give the selection rule among upcoming/due/completed payout variants.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond annotations: server-side auth injection, the 30-per-10s throttle with 429/5xx retry, and a precise error taxonomy (401/403/404/422). However, the boilerplate clause 'replaces the fields you send on an existing record' is inaccurate for a tool whose only parameter is id — there are no user-supplied fields to replace — which slightly undermines the disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well structured with labeled sections (Behavior, Returns, Use when) and a front-loaded WRITE/PUT marker that orients the agent immediately. The only wasteful content is the inapplicable 'replaces the fields you send' sentence; otherwise each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, this is nearly complete: it specifies return format, error semantics, rate limiting, auth requirements, and related tools. The notable gaps are not naming suspend_user as the inverse operation and the slightly misleading field-replacement clause.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the id parameter already documented as 'User id or email (encoded string).' The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with 'Unsuspends a user' — a specific verb and resource, reinforced by the title annotation 'Unsuspend a user' and the HTTP path PUT /v2/users/{id}/unsuspend. It is immediately distinguishable from inverse and adjacent siblings like suspend_user and update_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section states to invoke it only when the user asked to change an existing record, advises reading the record first, and routes to the create tool if the record does not exist. It lists related Users tools for navigation, though it never explicitly contrasts with suspend_user or update_user, leaving some exclusion logic implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only, but the description adds substantial behavior beyond that: auth is injected server-side, calls are throttled to 30 per 10 seconds and retried on 429/5xx, non-2xx responses surface as tool errors with status and API error payloads, and multiple query params are combined with AND. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections and front-loaded with the read-only GET nature. Minor redundancy exists: read-only is emphasized in the emoji, the Behavior section, and the Use-when section, and pagination is mentioned twice. Still, each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only paginated list tool with no output schema, the description covers behavior, error semantics, rate limiting, auth handling, pagination, filtering behavior, and use cases. Nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents every parameter. The description adds valuable cross-parameter semantics: all provided filters apply via AND, results are paged at 50 per page, and the page parameter should be used to walk pages. This goes beyond the schema without duplicating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets event logs and returns a paginated list of all event logs for the school. It is distinct in resource and behavior, but it does not explicitly differentiate from the sibling tool get_school_events, so it falls short of a perfect distinction score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: safe to call speculatively for lookups and reporting, and not for changing anything. However, the alternative is only a generic 'matching write tool' rather than a named sibling tool, so the when-not guidance is clear but the alternative is underspecified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond by disclosing server-side auth injection, throttling to LearnWorlds' 30-per-10s cap, retry on 429/5xx, sort order, pagination defaults, and per-status error semantics (401/403/404/422). Nothing contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections (Behavior, Parameters, Returns, Use when) and front-loads the safety badge and endpoint. The expanded error-code list is slightly verbose for a tool with one optional parameter, but each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-parameter read tool with no output schema, the description covers purpose, paging, sort order, auth, throttling, retries, and error behavior — the agent has everything needed to call it safely. Minor glitch: 'default limit of 20 users per page' appears to be a copy-paste from a user-oriented tool and should read 'seat offerings.'
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents `page` including its out-of-range clamping behavior. The description only adds 'walk them with `page`,' which reinforces pagination usage but adds no new semantic detail — the high-coverage baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource+scope: 'Get all seat offerings. Returns a list of all seat offerings of the school,' with ordering and pagination made explicit. The '🟢 READ-ONLY · GET /v2/seats' header plus the named sibling tools distinguish it clearly from per-item and write operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use when: safe to call speculatively for lookups and reporting. Not for changing anything — use the matching 🟡 write tool' provides an explicit when-to-use and a clear exclusion, and related seat tools are named. However, no decision rule separates it from the closely related get_specific_seat_offering (list vs single-item lookup).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations, explaining non-idempotency in concrete terms ('a repeated call can duplicate the effect'), server-side auth injection, throttling under the 30-per-10s cap, retries on 429/5xx, and the exact error-payload semantics for non-2xx replies. This is rich, actionable behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Behavior, Parameters, Returns, Use when) and front-loaded with the WRITE status and endpoint. It is somewhat verbose but every section earns its place. There is a small redundancy between 'creates data' in the header and 'creates a record or triggers an action' in the Behavior section.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating, non-idempotent tool with no output schema, the description covers essentially everything needed: endpoint, HTTP method, auth, rate limiting, retry behavior, return format, error codes, preconditions, and a related sibling. No critical information for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all three parameters (100% coverage), so the baseline is 3. The description adds important value by clarifying that the full JSON payload goes in the single body argument, is forwarded verbatim, and that while the spec marks body optional, this endpoint actually expects one. It doesn't expand on id/cid beyond their schema descriptions, which is acceptable given the coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Resets the user's progress on a course or learning activity level,' which matches the tool name and endpoint. The action is unambiguous even without sibling comparison. A minor flaw is the 'Use when: only when the user asked to create this' phrase, which uses 'create' instead of 'reset' and slightly muddies the intended trigger.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit 'Use when' section: invoke only on explicit user request, verify existence with a 🟢 read tool first, and names mark_as_complete as the related progress-update tool. This gives a clear decision path, though it could be stronger by explicitly stating 'use mark_as_complete for completion requests' instead of just calling it 'related.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing that calls affect the live school, are not idempotent, have server-side auth, are throttled at 30-per-10s, and retried on 429/5xx. It also explains the exact return format and error status meanings. This fully informs the agent of side effects and operational constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but tightly organized with labeled sections: Behavior, Parameters, Returns, Use when, and Related tools. Every section provides actionable information, and the most important facts—write operation, endpoint, idempotency—are front-loaded. No content feels redundant or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by specifying the response format, error behavior, auth requirements, rate limits, and preconditions. It also names related Promotions tools for navigation. For a mutating tool with side effects, this is a thorough and complete definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers pid and nested body fields, but the description adds critical meaning by explaining that the whole JSON payload goes into the single `body` argument and is forwarded verbatim, despite the schema marking it optional. This resolves a real ambiguity. It does not elaborate on the example's `prefix` field, but the core parameter behavior is well explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Creates a coupon for the promotion specified by the provided promotion id,' and reinforces it with the HTTP endpoint. It is specific about the resource and operation. However, it only lists related sibling tools like create_coupons_promotion_bulk without explicitly explaining how this tool differs from them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a dedicated 'Use when' section: 'only when the user asked to create this' and advises checking with a read tool that the target exists and the record is not already there. This gives clear precondition guidance. It does not explicitly contrast with the bulk creation sibling, so the reader must infer when to choose one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description adds substantial context on top: auth injected server-side rather than by the model, throttling under LearnWorlds' 30-per-10s cap, retry behavior on 429/5xx, sort order (most recent first), 50-per-page pagination, AND semantics for combined query params, and precise HTTP error mappings (401/403/404/422). No contradiction with annotations; 'creates, changes and deletes nothing' aligns with readOnlyHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into labeled sections (Behavior, Parameters, Returns, Use when, Related tools) and front-loads the READ-ONLY badge and HTTP endpoint. It is longer than average, but each section earns its place by covering safety, pagination, error semantics, and usage routing. Minor redundancy: 'Get affiliate payments' followed immediately by 'Returns a list with all the affiliate payments' is a near restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter list tool with no output schema, the description covers everything an agent needs: return format ('HTTP <status> followed by the LearnWorlds JSON response body'), non-2xx error handling with status codes, pagination parameters, ordering, safety profile, and when to use it. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (id and page) are already fully documented including the default value and last-page fallback behavior. The description adds only a marginal hint ('walk them with `page`') and the AND-operator note for query params, which is useful but not necessary given the schema's completeness. Baseline 3 is appropriate since the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Get affiliate payments. Returns a list with all the affiliate payments.' The phrase 'all the affiliate payments' distinguishes it from the status-filtered sibling payout tools (due/upcoming/completed), and five related affiliate tools are named explicitly, so an agent can tell this tool apart without opening sibling schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit directive: 'Use when: safe to call speculatively for lookups and reporting. Not for changing anything — use the matching 🟡 write tool.' This clearly states when the tool is appropriate and what it is not for. However, it does not spell out exclusions against the sibling payout tools (e.g., when to choose get_due_affiliate_payouts over this one), leaving that discrimination to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint and destructiveHint annotations by disclosing that auth is injected server-side, calls are throttled under LearnWorlds' 30-per-10s cap and retried on 429/5xx, and non-2xx responses surface as tool errors with specific status meanings. This gives the agent rich context about rate limits, error handling, and operational safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into clear sections — purpose, Behavior, Returns, Use when — with front-loaded read-only status and endpoint path. Each sentence carries useful information, and there is no redundant filler despite the moderate length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description comprehensively covers behavioral, auth, throttling, and error semantics, which is strong for a tool with only two simple parameters. However, since there is no output schema, the return value description ('LearnWorlds JSON response body') is vague and does not explain what analytics fields will be present; a bit more detail about the payload shape would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('Course title Id' and 'Learning activity id'). The description merely repeats the concept of 'course id and learning activity id' without adding format constraints, examples, or clarification of the ambiguous 'Course title Id' label, so it adds no real value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get analytics for a learning activity' and clarifies the scope by specifying the course id and learning activity id. It also distinguishes itself from related reporting tools like get_analytics_course and get_user_progress, so an agent can identify 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'safe to call speculatively for lookups and reporting' and 'Not for changing anything — use the matching 🟡 write tool.' It names related reporting tools as alternatives, but does not explain when to prefer this tool over get_analytics_course, get_user_progress, or get_user_progress_per_course, so the selection criteria between these siblings remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only, idempotent, and non-destructive, and the description adds substantial behavior beyond that: server-side auth injection, throttling under LearnWorlds' 30-per-10s cap, retries on 429/5xx, and detailed non-2xx error mapping. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a badge, endpoint line, behavior, returns, and usage guidance. It is mostly tight, though the first two sentences repeat the same idea ('Get the progress...' / 'Returns information about the progress...'), which is minor redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only lookup with no output schema, the description is complete: it explains what it returns, how errors surface, auth handling, throttle/retry behavior, and when it is appropriate to use. An agent has enough to invoke it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is fully covered by the input schema description ('Job id'), so the description doesn't need to add much. It does echo the URI template {id}, but provides no extra semantics beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the exact HTTP method and endpoint, then states 'Get the progress of an asynchronous action' — a specific verb and resource. This clearly distinguishes the tool from the many sibling GET tools, none of which target async action progress.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly says it is safe for speculative lookups and reporting, and warns it is not for changing anything. It references a matching write tool, though it doesn't name the specific sibling; the guidance is still clear enough to route behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations: it states read-only behavior, server-side auth injection, throttling under a 30-per-10s cap, retry on 429/5xx, return format, and status-code meanings. These details are not present in annotations and materially shape invocation expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is organized into short labeled sections (Behavior, Returns, Use when) and is front-loaded with the read-only summary. A small amount of redundancy exists between the title line and the opening sentence, but the overall structure keeps it scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool with rich annotations, the description covers input, output shape at the HTTP level, error behavior, rate limits, and policy. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is already described as 'The unique identifier of the seat offering.' The description adds the endpoint path and lookup semantics but no additional format or source guidance, so it meets the baseline without significantly extending parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get a specific seat offering') and identifies the input by id, distinguishing it from list and user-membership siblings via the '/v2/seats/{id}' endpoint. The explicit return statement reinforces the single-record lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear use case ('safe to call speculatively for lookups and reporting') and explicitly redirects writes to the matching 🟡 write tool. It names related seat-offering tools, though it doesn't detail when to choose this over sibling read tools like get_seat_offerings or get_users_seat_offering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing auth injection, rate limiting (LearnWorlds 30-per-10s cap), retry behavior on 429/5xx, and the error payload structure for non-2xx responses. This gives the agent a realistic picture of side effects and failure modes, with no contradiction to readOnlyHint/idempotentHint/destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than strictly necessary but well-structured with labeled sections (Behavior, Parameters, Returns, Use when). It front-loads the core purpose and every section adds useful information, though some redundancy with annotations exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers return format, pagination semantics, error handling, auth, and rate limiting. It also points to related tools, making it complete for an agent to select and invoke this tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single parameter is 100%, and the description merely reinforces pagination with 'walk them with page.' It adds some intent context but does not materially enrich the schema's description of the page parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Gets all user groups' and specifies it returns a list of all user groups of the school, with sorting and pagination details. This unambiguous verb+resource statement distinguishes it from singular 'get_user_group' and other sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'safe to call speculatively for lookups and reporting' and 'Not for changing anything — use the matching 🟡 write tool.' It also lists related user group tools, but does not explicitly contrast when to prefer this list tool over get_user_group or get_users_user_group beyond the plural/scope distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the operation is read-only against the live school, creates/changes/deletes nothing, uses server-side auth injection, throttles to LearnWorlds' 30-per-10s cap, retries on 429/5xx, and explains the return/error format. This is rich behavioral context that goes well beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections for behavior, returns, and usage, and the key information is front-loaded. The first two sentences are slightly redundant, but the rest is dense and purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter schema and no output schema, the description covers everything needed: what the call does, auth handling, rate limiting, retry behavior, response format, error semantics, and safe use cases. An agent can invoke this tool correctly without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, id, and the schema already describes it as 'User Id or email (encoded string)' with 100% coverage. The description reinforces the role of the user in the lookup but does not add meaningful new semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get user groups that a user is member of' and further clarifies it returns a list for the specified user. The user-scoped phrasing distinguishes it from sibling tools like get_user_groups and get_users_user_group even without naming them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use it: 'safe to call speculatively for lookups and reporting.' It also gives a clear exclusion by saying it is not for changing anything and points toward a matching write tool. However, it does not name the exact alternative write tool or directly compare against get_user_groups, so the guidance is clear but not fully exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description explains that auth is injected server-side, calls are throttled to LearnWorlds' 30-per-10s cap and retried on 429/5xx, and it details return and error behavior including specific HTTP status meanings. This is substantial context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections and front-loaded purpose. It is slightly redundant in the opening sentences ('Get user progress per course' followed by 'Returns information about the user progress...'), but overall every major section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool with no output schema, this description is exceptionally complete: it covers endpoint, purpose, behavioral guarantees, auth, rate limiting, retry behavior, error semantics, and usage context. No critical operational information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented with their types and meanings. The description only restates that the user id and course id are used, adding no meaningful semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation (read-only lookup of per-course user progress), the exact resource via endpoint path, and the key output detail: a breakdown per learning activity. It also names related reporting tools, so an agent can place it among siblings even though the distinction is not spelled out explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'Use when: safe to call speculatively for lookups and reporting' and 'Not for changing anything — use the matching 🟡 write tool.' It lists related reporting tools, but does not provide a precise decision rule for choosing this tool over get_user_progress or get_analytics_course.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses substantial behavior beyond the annotations: server-side auth injection (model never handles tokens), throttling to LearnWorlds' 30-per-10s cap with retry on 429/5xx, 20-per-page pagination, ordering, and a complete error mapping (401/403/404/422). 'Creates, changes and deletes nothing' reinforces rather than contradicts the readOnlyHint=true, destructiveHint=false annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Longer than average, but efficiently organized with bolded labels (Behavior, Parameters, Returns, Use when) and a one-line summary up front. Every section carries operational information an agent needs to call the tool safely; the Returns section is the most verbose but earns its place given there is no output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description shoulders return-value disclosure and delivers the response shape ('HTTP <status> + LearnWorlds JSON body'), ordering, and pagination semantics, plus auth, throttling, and error handling. The only meaningful gap is that the exact JSON body structure is left unspecified, which an agent consuming the result would need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value beyond the schema by tying page + items_per_page into a pagination walk strategy ('walk them with page and size each page') and revealing a 20-per-page default the schema doesn't state. The users parameter is left to the schema, which already documents it fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource ('assessment responses') with a specific verb ('Get ... Retrieves') and adds distinctive behavioral detail: most recent submission first, paginated at 20 per page. It also anchors itself in the sibling space by explicitly labeling the related assessment tools and declaring itself the read-only lookup rather than the write path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use when: safe to call speculatively for lookups and reporting' gives explicit positive context, and 'Not for changing anything — use the matching 🟡 write tool' gives an explicit exclusion. However, the named alternatives (review_submission_user_s_assessment_submission, get_form_responses) are listed without selection conditions, so an agent must still infer which assessment tool fits a given task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds valuable context: auth is injected server-side, calls are throttled and retried, responses include HTTP status and the JSON body, and non-2xx errors surface with specific meaning for 401/403/404/422. This goes well beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clear labeled sections: Behavior, Returns, Use when, and Related tools. Every sentence adds useful information, and the most important facts are front-loaded near the start.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter lookup with no output schema, the description is complete: it covers the operation, response format, error handling, authorization, rate limiting, and usage boundary. Nothing an agent needs to safely invoke this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the single id parameter, so the baseline is 3. The description only restates that the post is 'specified by the provided post id' and does not add format, source, or validation details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get a community post' and names the REST endpoint, clearly identifying the exact resource and operation. It distinguishes this singular lookup from the plural get_community_posts by emphasizing the provided post id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use the tool ('safe to call speculatively for lookups and reporting') and when not to use it ('Not for changing anything'), and it lists related Community tools. However, the 'matching 🟡 write tool' is not named, and no obvious update_community_post sibling exists, so the routing guidance is slightly vague even though the overall intent is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description goes well beyond them: it states auth is injected server-side, rate limiting/retry behavior, pagination specifics (50 per page, sorted order), and detailed non-2xx error semantics. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-labeled and information-dense, with the read-only and endpoint context front-loaded. Minor redundancy exists between the opening line and the second sentence, but every section earns its place given the pagination, auth, and error behavior that must be conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description covers the return envelope, error handling, pagination, ordering, and safety profile. It does not enumerate the exact JSON fields of a coupon usage record, but it conveys enough for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaningful operational meaning: 'results are paged — walk them with page', the 50-per-page limit, and ordering by most recently created payment. This helps the agent use the page parameter correctly beyond the schema's terse description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get coupon usage') and unpacks it with concrete details: coupon usage details plus associated payments, sorted and paginated. The 'Related Promotions tools' list and read-only marker also help distinguish it from sibling promotion tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says it is safe to call speculatively for lookups and reporting, and warns against using it for changes, pointing to the matching write tool. It lists related Promotions tools but does not precisely contrast this tool against the closest read sibling, get_promotions_coupons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Behavior is disclosed in depth beyond the annotations: read-only against the live school, auth injected server-side, throttling under the API cap, retry on 429/5xx, and detailed non-2xx error semantics with specific status codes. This far exceeds what the annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections: behavior, returns, errors, and usage. Despite covering a lot of operational detail, every sentence adds practical value and the critical read-only nature is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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, the description is complete: it covers auth, rate limiting, retries, response format, error mapping, when to use, and when not to use. No output schema exists, but the return format is explained sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single id parameter with 100% coverage. The description restates that the id identifies the course and appears in the URL path, but adds no new format, type, or usage nuance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: getting a single course by id via GET /v2/courses/{id}. It distinguishes itself from plural/listing tools like get_courses and from write operations by explicitly marking itself READ-ONLY and naming related course tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it ('safe to call speculatively for lookups and reporting') and when not to ('Not for changing anything'), pointing to a matching write tool. However, the write alternative is not named directly by tool name, though update_course appears in the related tools list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: auth is injected server-side and 'never by the model', calls are throttled under LearnWorlds' 30-per-10s cap and retried on 429/5xx, and non-2xx replies surface with status plus 401/403/404/422 meanings. None of this contradicts readOnlyHint, idempotentHint, openWorldHint, or destructiveHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the READ-ONLY marker, endpoint, and core behavior, then organized into labeled Behavior/Parameters/Returns/Use-when sections. Each section earns its place; the only mild redundancy is 'creates, changes and deletes nothing' mirroring the annotations, which works as a safety cue rather than waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Very complete for a 2-parameter read-only tool with no output schema: it covers return shape, error payloads, auth, rate limits, retries, and usage routing. The remaining gaps are minor — no field-level enumeration of what 'course enrollment data' contains, and no explicit disambiguation from get_users_per_course.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 contributes operational param guidance the schema lacks: the 50-enrollments-per-page limit and the instruction to walk results with `page`. This tells the agent how many paged calls may be required, which is genuinely additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Get courses (enrollments) of user' — with explicit user scoping and the HTTP endpoint GET /v2/users/{id}/courses. The pagination detail (50 per page) further pins down the return shape. This is unambiguous against siblings like get_courses or the inverse get_users_per_course.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gives when-to-use ('safe to call speculatively for lookups and reporting') and when-not ('Not for changing anything — use the matching 🟡 write tool'). It names related Users tools but without selection conditions among them, so an agent must still infer which specific lookup fits a given need.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/destructive annotations, it discloses auth handling, server-side injection, throttling to LearnWorlds' cap, retry behavior on 429/5xx, the raw output shape (HTTP status + JSON body), and per-status error semantics. This gives the agent a realistic picture of side effects and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the endpoint and helpful read-only marker, then uses labeled sections (Behavior, Returns, Use when) to pack dense, useful constraints without repetition. Every sentence adds operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only lookup with no output schema, the description covers what returns, how errors surface, what auth and throttling do, and when to use it. The only mild gap is a precise comparison with get_payment/get_payments, but the named siblings plus clear purpose make the tool safely callable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter is fully described in the schema ('Payment Id or Transaction id'), so schema coverage is 100%; the description mainly reinforces that the lookup is per payment. It adds no format, provenance, or edge-case guidance for the id beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the exact verb, resource, and endpoint ('Get invoice link per payment', GET /v2/payments/{id}/invoice-link) and states the concrete return payload (invoice number and private expiring link). It is clearly distinguishable from sibling payment tools and the broader get_* family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit usage context ('safe to call speculatively for lookups and reporting') and an explicit exclusion ('Not for changing anything — use the matching 🟡 write tool'). It names related Payments tools (get_payment, get_payments) as alternatives, though it does not spell out the exact selection rule among those three.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces and expands on these by stating it creates, changes, and deletes nothing. It adds valuable context about server-side auth, throttling, retry behavior, and error response semantics beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labels: Behavior, Parameters, Returns, Use when. It is detailed yet efficient; every section adds operational value without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool with one optional parameter and no output schema, the description covers behavior, auth, rate limiting, pagination, response format, error handling, and appropriate use cases. Nothing important is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already documents the page parameter including default and out-of-range behavior. The description adds only a mild reminder to 'walk them with page', which is useful but does not substantially extend the schema's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the verb and resource clearly: 'Get leads. Returns a list with all the leads of the school.' It also adds scoping detail (all school leads), sorting, and pagination. This distinguishes it from related tools like get_leads_per_affiliate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit 'Use when' section: safe to call speculatively for lookups and reporting, and says not to use it for changing anything. It references the matching write tool but does not name a specific sibling, so exclusions are present but alternatives remain somewhat generic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds rich behavioral context: it states auth is injected server-side, calls are throttled to respect LearnWorlds' 30-per-10s cap and retried on 429/5xx, and it details the return format and error payload semantics for 401/403/404/422. This goes well beyond what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear labeled sections, front-loads the read-only nature and endpoint, and every sentence delivers useful information: behavior, auth, throttling, returns, errors, and usage guidance. It is longer than minimal but not bloated; relative to the amount of operational detail, it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one well-documented parameter and no output schema, the description compensates fully by explaining what is returned (HTTP status plus JSON body), how errors surface, and the operational constraints. It leaves no critical gap for an agent deciding whether and how to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the single parameter 'id' as 'User id or email' with 100% coverage. The description only repeats 'provided user id' without adding format, validation rules, or usage nuances beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get products of user' with the endpoint GET /v2/users/{id}/products, and clarifies it returns a list of all products for the specified user id. This clearly identifies the operation, though it does not explicitly differentiate from sibling tools beyond naming related Users tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'safe to call speculatively for lookups and reporting.' It also provides a when-not: 'Not for changing anything — use the matching 🟡 write tool,' and lists related Users tools as alternatives, giving an agent concrete routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes well beyond the annotations: it discloses server-side auth injection, rate-limit throttling/retry behavior, the exact return format (HTTP status + JSON body), and maps specific non-2xx statuses to likely causes. This is rich behavioral context that annotations alone do not provide, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear labeled sections (Behavior, Returns, Use when) and is front-loaded with the key verb and resource. Each sentence adds distinct value, and nothing is redundant or wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 no output schema, the description is complete: it covers what is returned, error behavior, auth, throttling, and appropriate usage. No critical information an agent would need to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the parameter described as 'Subscription plan Id'. The description repeats the id in prose but adds no new semantic depth beyond what the schema already provides. Baseline 3 applies given complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get subscription plan') and resource ('subscription plan specified by the provided subscription plan id'), and explicitly names the sibling tool get_list_subscription_plans to disambiguate. An agent can immediately understand what this tool does and how it differs from the plural list variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly states it is safe for speculative lookups and reporting, and explicitly says not for changing anything, pointing to the write tool. It mentions the related Subscription plans tool get_list_subscription_plans, though it does not deeply contrast when to choose list vs single-get. Still, the usage context and exclusion are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds valuable behavioral context: it is a read-only lookup that creates/changes/deletes nothing, auth is injected server-side, calls are throttled and retried, and non-2xx responses surface as errors with specific status meanings. This goes well beyond the readOnlyHint and idempotentHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections: purpose, behavior, returns, use-when, and related tools. Every sentence adds information, and the core purpose is front-loaded before the supporting detail. The length is justified by the absence of an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only lookup with no output schema, the description is complete: it explains what the tool returns, how errors are presented, what the auth/rate-limit behavior is, and which sibling tools are related. An agent has enough context 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the single required parameter 'id' is already described as 'The unique identifier of the user group' in the input schema. The description merely restates that concept ('provided user group id') and adds no new format, source, or validation detail, so the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Get a user group' and specifies it returns the user group identified by the provided id. The singular-by-id framing distinguishes it from the plural listing tool get_user_groups and other related user-group tools, so an agent can tell 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it ('safe to call speculatively for lookups and reporting') and when not to ('Not for changing anything — use the matching 🟡 write tool'), and it lists related user-group tools. However, it does not explicitly contrast this read tool with the other read-oriented siblings like get_user_groups or get_users_user_group, leaving the choice among those partially implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing non-idempotency, duplicate effects, server-side auth injection, throttling/retry behavior, and detailed error/response semantics for non-2xx statuses. This is exactly the kind of behavioral context annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections (Behavior, Returns, Use when) and front-loads the critical WRITE status and endpoint. It is slightly longer than strictly necessary, but every section carries operational value, and the redundancy between 'creates data' and 'Behavior' is minor.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully explains the return format, error behavior, auth model, rate limiting, and when to call the tool. Given the low parameter count and complete schema descriptions, nothing essential is missing for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and both parameters have clear descriptions ('Unique identifier of the user group' and 'User Id or email (encoded string)'). The description adds the endpoint path context but does not meaningfully expand parameter semantics beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Add a user to a user group' with the exact POST endpoint. It distinguishes itself from sibling tools by labeling it as a WRITE/creates-data operation and listing related user-group tools like remove_user_user_group and get_users_user_group, so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use when: only when the user asked to create this' and instructs the agent to verify with a read tool that the target exists and the record is not already present. It also names related sibling tools, giving clear routing guidance and exclusion context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses non-idempotency and duplicate-effect risk, server-side auth injection, throttling under LearnWorlds' 30-per-10s cap with retry on 429/5xx, and exact non-2xx error mappings. This is substantial added behavioral context and is consistent with 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections — Behavior, Parameters, Returns, Use when — and front-loads the write indicator and endpoint. No sentence is filler; the length is justified by the auth, retry, and error details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, it describes the response format and error surfaces clearly. The only notable gap is that the body payload structure for a course section is not described, which would help an agent construct or validate the payload when the user does not supply one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Though schema coverage is 100%, the description adds meaningful nuance: 'body' is expected even though the spec leaves it optional, and the entire JSON payload should be forwarded verbatim in that single argument. This compensates for the schema's deliberately hidden body reference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource — 'Creates a new course section in the course, specified by the course id' — and reinforces it with the endpoint path. This is unambiguous against sibling tools like create_course because the target resource is specifically a course section, not a course.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit usage rule: 'Use when: only when the user asked to create this,' and advises checking with a read tool that the course exists and the section is not already present. It names related Courses tools but could more strongly contrast with update_course or create_course for non-create intents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnlyHint=false, destructiveHint=true, and idempotentHint=true, and the description aligns with and substantially extends them. It discloses permanent destruction ('no undo from this server'), async continuation after the initial response, server-side auth injection, throttling under the 30-per-10s cap, retry on 429/5xx, and per-status-code error semantics — exactly the behavioral context the annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but deliberately structured with labeled sections (Behavior, Returns, Use when) and a front-loaded destructive warning. Nearly every sentence carries operational value for a destructive, asynchronous, rate-limited call; the error-code enumeration is slightly verbose but aids agent-side error diagnosis.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema present, the description correctly compensates by disclosing success status codes, empty-on-success body, and how non-2xx replies surface as tool errors. For a one-parameter destructive tool, it covers prerequisites (user confirmation), auth model, rate limits, retry policy, alternatives, and related tools — nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the id parameter is fully documented in the schema itself. The description only restates that the record is 'identified by its unique ID,' adding no format, syntax, or constraint detail beyond the schema. Baseline 3 is appropriate when the schema carries the full load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific action verbs ('Deletes', 'removes') with an explicit resource ('specific seat offering') and scope ('identified by its unique ID'), and discloses the asynchronous execution mode. It clearly distinguishes from siblings by naming update_seat_offering and remove_user_seat as different operations, so an agent can disambiguate without opening other tool definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains an explicit 'Use when' clause with a hard gate ('only after the user confirms the removal'), plus an explicit exclusion condition ('To merely revoke access or deactivate, use the matching update or unenroll tool instead'). It also lists the related multi-seat sibling tools, giving the agent concrete routing alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations: it discloses permanent deletion with 'no undo from this server,' asynchronous processing, server-side auth injection, throttling and retry behavior, HTTP 200/204 success shape, and error payload specifics for 401/403/404/422. This is rich behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative, with the destructive warning front-loaded and sections for behavior, returns, and usage guidance. Minor redundancy exists between 'Deletes a specific user group' and 'This endpoint removes a user group,' but every major clause contributes operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description covers the endpoint, async behavior, permanence, auth, throttling, success and error responses, and when to avoid it. An agent has enough context to decide whether to call it and what to expect in response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single 'id' parameter already described as 'The unique identifier of the user group.' The description adds little beyond stating the deletion is by unique ID, so the schema carries the parameter-semantics burden and the description meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Deletes a specific user group' via DELETE /v2/user_groups/{id}. It names the exact object type and operation, and the sibling-tool list shows distinct related tools for adding, updating, and removing users from groups, so this tool is clearly differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'only after the user confirms the removal.' It also gives alternatives for non-destructive scenarios: 'To merely revoke access or deactivate, use the matching 🟡 update or unenroll tool instead,' and lists related user-group tools. This is fully actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing read-only behavior against the live school, server-side auth injection, throttling under a 30-per-10s cap, retry behavior on 429/5xx, pagination semantics, sort order, and detailed error-response handling. This gives the agent a strong model of side effects and operational constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Behavior, Parameters, Returns, Use when) and front-loads the read-only nature. There is mild redundancy in opening with 'Get active installments' and then 'Return a list with active installments of users,' but overall every other sentence carries useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of explaining return behavior, and it does: HTTP status plus JSON body, non-2xx error surfaces, pagination boundary behavior, and filter composition. Given the 4 optional parameters and the API's operational context, nothing essential is missing for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaningful cross-parameter semantics: multiple query params are combined with the AND operator, and pagination is explicitly linked to the `page` parameter. This clarifies how the parameters interact, which the schema alone does not communicate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Get active installments') and immediately states the exact endpoint. It clarifies scope (active installments of users), ordering (user creation date descending), pagination (50 per page), and filtering semantics, so an agent can distinguish this from other read/list tools like get_payments or get_users_subscriptions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly says it is safe to call speculatively for lookups and reporting, and explicitly warns against using it for changes, pointing to 'the matching 🟡 write tool.' It does not name a specific sibling alternative, but the guidance is clear enough for an agent to decide when this tool applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the call creates/changes/deletes nothing, that auth is injected server-side, that calls are throttled and retried on 429/5xx, and that non-2xx responses surface as tool errors with specific status meanings. This substantially exceeds the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well organized with clear Behavior, Returns, and Use when sections, and most sentences add value. Minor redundancy exists: 'Get a bundle' overlaps with the following sentence and the READ-ONLY label, but the overall structure is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 no output schema, the description is complete: it specifies the endpoint, auth behavior, rate limiting, retry policy, return format, and error semantics. An agent has everything needed to invoke and interpret the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter id is already fully described in the schema as 'Unique identifier of the bundle,' providing 100% coverage. The description only rephrases this as 'provided bundle id' without adding format, constraints, or examples, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get a bundle' and 'Returns the bundle specified by the provided bundle id.' It clearly differentiates this singular lookup tool from the plural sibling get_bundles, and the read-only nature is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly says it is safe to call speculatively for lookups and reporting, and instructs not to use it for changes, directing the agent to the matching write tool. It also points to the related get_bundles tool, giving clear routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: auth is injected server-side, calls are throttled under LearnWorlds' 30-per-10s cap, 429/5xx retries occur, and non-2xx responses surface as tool errors with specific status meanings. It also notes pagination behavior and that nothing is created or deleted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a READ-ONLY tag and endpoint, then organized into behavior, parameters, returns, and use-when sections. It is somewhat long, but each sentence carries useful information and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only GET tool with no output schema, it fully covers return format, error handling, auth, rate limits, pagination, and usage context. It also names related course tools, giving the agent enough context to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each parameter. The description adds practical guidance on walking pages with `page` and sizing them with `items_per_page`, plus error semantics, though the 'limit of 20 grades per page' line sits awkwardly next to the schema's max of 200.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: retrieves grades for all enrolled users in a specified course. It is clearly distinct from course CRUD siblings like get_course, update_course, or get_courses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it — safe speculative lookups and reporting — and explicitly says not to use it for changing anything. It points to a 'matching write tool' but does not name a specific grade-write sibling, so the routing is slightly generic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing server-side auth injection, throttling under LearnWorlds' rate cap, retry behavior on 429/5xx, the HTTP status + JSON body return format, and specific error status meanings. No contradiction with readOnlyHint or destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into endpoint, behavior, parameters, returns, and use-when sections, with the read-only status front-loaded. It is detailed but not bloated, though it does repeat information already conveyed by annotations such as read-only behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only tool with no output schema, the description covers everything needed to call it correctly: endpoint, auth, rate limiting, retries, pagination, and error handling. The agent knows what to expect and how to interpret non-2xx responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both id and page with 100% coverage. The description adds useful pagination context: results are paged, use the page parameter to walk pages, and each page has a limit of 20 customers. This is extra value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: it retrieves all customers connected to an affiliate id, with sorting and pagination details. This clearly distinguishes it from siblings such as get_leads_per_affiliate by focusing on customers rather than leads or payments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' guidance, saying it is safe for speculative lookups and reporting, and warns not to use it for changes, directing the agent to the matching write tool. It also lists related affiliate tools, though it does not explicitly spell out the exact conditions for choosing between this and each listed sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark this as read-only, idempotent, and non-destructive, and the description reinforces this by stating it 'creates, changes and deletes nothing.' It adds valuable context beyond annotations: server-side auth injection, throttle handling, retry behavior, sorting order, pagination limit, and detailed error-surface semantics for 401/403/404/422.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for behavior, parameters, returns, and usage. It is slightly repetitive, restating 'read-only' and the resource name in multiple places, but the added details are relevant and the front-loaded summary makes it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description explains the return format, error handling, authentication, rate limiting, sorting, pagination, and safety profile. For a two-parameter read-only endpoint, this gives an agent everything needed to call it correctly and anticipate outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both parameters. The description adds meaning beyond the schema by explaining pagination behavior: results are paged, 'walk them with `page`,' the list is sorted with most recent first, and each page is limited to 20 leads.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: 'Get all leads per affiliate' and 'Retrieves all the leads connected with the affiliate specified by the provided affiliate id.' It also differentiates itself by listing the related Affiliates tools, making its scope clear relative to siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use when: safe to call speculatively for lookups and reporting. Not for changing anything — use the matching 🟡 write tool.' It names the related Affiliates tools but does not give specific conditions for choosing one sibling over another, so it falls just short of full routing precision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description significantly expands on annotations by disclosing server-side auth injection, throttling and retry behavior, response shape, and error semantics for common HTTP statuses. It reinforces the read-only and non-destructive nature while adding operational detail that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and front-loaded safety/read-only information. There is minor redundancy in saying 'Get a list' and then 'Returns a list of all subscription plans,' but every other sentence contributes useful operational context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers purpose, pagination, safety, authentication, rate limiting, and error handling. Nothing critical is missing for an agent to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaningful guidance on how to use the single parameter, 'page', by explaining pagination and the 50-item page limit. This goes slightly beyond the schema's basic parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a list of subscription plans, identifies the endpoint, and explains the sorting and pagination behavior. It also distinguishes the purpose from the related single-plan tool, get_subscription_plan, so the agent can select the right granularity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use the tool ('safe to call speculatively for lookups and reporting'), when not to use it ('Not for changing anything'), and points to the matching write tool. It mentions the related get_subscription_plan tool, though it does not fully specify the exact conditions for choosing one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations: it discloses sorting order (most recent first), pagination limit (20 per page), server-side auth injection (model never handles tokens), rate limiting (30-per-10s cap), retry behavior on 429/5xx, and the exact error surface (401/403/404/422). It aligns with readOnlyHint=true by stating it 'creates, changes and deletes nothing.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a '🟢 READ-ONLY · GET /v2/promotions' summary line and organized into labeled sections (Behavior, Parameters, Returns, Use when), which makes scanning easy. It is slightly verbose relative to the tool's single-parameter complexity, with minor redundancy against annotations and a somewhat long related-tools list, but every section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the Returns section correctly explains the response shape (HTTP status + LearnWorlds JSON body) and error payloads — essential information an agent would otherwise lack. Combined with pagination, auth, throttling, and usage guidance, nothing needed to invoke this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents `page` with its default and out-of-range behavior. The description adds only light context ('results are paged — walk them with `page`'), tying the parameter to the 20-per-page limit, which is useful but not substantial beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get promotions. Returns a list with all the promotions of the school.' It adds scoping detail (all promotions, sorted by recency) and explicitly names sibling tools such as get_promotion, create_promotion, and create_coupon_promotion, so an agent can distinguish this list operation from singular and write variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section is explicit: 'safe to call speculatively for lookups and reporting. Not for changing anything — use the matching 🟡 write tool.' It names the write alternatives (create_coupon_promotion, create_coupons_promotion_bulk, create_promotion) and lists related Promotions tools, giving clear routing guidance with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnlyHint annotation: it states the operation creates/changes/deletes nothing, auth is injected server-side, calls are throttled under LearnWorlds' 30-per-10s cap, and retried on 429/5xx. It also details error statuses (401, 403, 404, 422) and how non-2xx responses surface. This is rich 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the read-only indicator and endpoint. Almost every section earns its place, though the first two sentences are mildly redundant: 'Get seat offerings that a user is member of' and 'Returns a list of all seat offerings that the specified user is a member of' restate the same idea.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 no output schema, the description covers everything needed to call it safely and interpret results: endpoint, return format, error semantics, rate limiting, retry behavior, and explicit use guidance. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the only parameter fully: 'User Id or email (encoded string)' with 100% coverage. The description adds no additional parameter-level meaning beyond referring to 'the specified user,' so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get seat offerings that a user is member of' and clarifies the result is a list of all seat offerings for the specified user. This clearly differentiates it from seat-offering siblings like get_seat_offerings or get_users_seat_offering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use when: safe to call speculatively for lookups and reporting' and 'Not for changing anything — use the matching write tool.' It also lists related Users tools, giving an agent concrete guidance on when this lookup is appropriate versus mutation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, the description adds substantial behavioral detail: auth is injected server-side, calls are throttled and retried, returns are HTTP status plus JSON body, and non-2xx replies surface as tool errors with specific status meanings. This fully discloses operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into clear labeled sections and is front-loaded with purpose. It is slightly longer than strictly necessary, with minor redundancy between the first two sentences, but every major section adds useful operational context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully explains the return shape, error behavior, auth model, rate limiting, and safe usage context. For a simple one-parameter read-only lookup, nothing essential is missing 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter 'id' as 'User Id or email', so the schema already carries the semantic weight. The description only refers to 'the provided user id' without adding new format or constraint details, matching the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get user role of a user') and clearly defines what the tool returns, including assigned resources where applicable. It is immediately distinguishable from sibling tools like update_user_role_user and get_user_roles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it ('safe to call speculatively for lookups and reporting') and when not to ('Not for changing anything — use the matching 🟡 write tool'), and names related tools including the write alternative. This gives an agent clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds read-only semantics beyond annotations: no creates/changes/deletes, auth injected server-side, throttling/retry behavior, pagination and error surfacing. This is valuable context the annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than minimal but structured with headers and packed with useful details. It is front-loaded with READ-ONLY and the endpoint, so the extra length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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, it covers purpose, pagination, sorting, auth behavior, throttling, and error handling. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, so baseline is 3; the description adds the actionable pagination pattern 'walk them with page and size each page with items_per_page' and notes the API default limit of 10 per page. This goes slightly beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the exact verb and resource: 'Get users of a community space' plus the endpoint. It clearly states the return is a paginated list of users in sorted order, and names related Community tools so it is distinguishable from get_community_space/get_community_spaces and the write tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit 'Use when...' section: safe for speculative lookups and reporting, and 'Not for changing anything — use the matching write tool'. It lists related Community tools, though it could more directly say 'use get_community_space for space metadata rather than its users'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: auth is injected server-side and never handled by the model, calls are throttled under a 30-per-10s cap and retried on 429/5xx, and the full error surface is mapped (401/403/404/422). 'Creates, changes and deletes nothing' is consistent with readOnlyHint=true — no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but earns its length through labeled sections (Behavior, Parameters, Returns, Use when) and front-loaded identification (READ-ONLY, GET endpoint, action). Each sentence carries functional content; the emoji markers aid quick scanning. Slightly heavier than strictly necessary, but nothing is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter, 0-required, no-output-schema lookup tool, this is complete: pagination mechanics, parameter combination, return envelope, error-to-tool-error mapping, API-rate expectations, and speculative use guidance are all covered. An agent can select and invoke this tool correctly with no further investigation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters, setting the baseline at 3. The description adds value beyond the schema by explaining combination semantics ('if more than one Query param is provided, then all of them will be applied — AND operator') and by explicitly instructing the agent to walk pages with the page parameter. This exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Get users subscriptions. Returns a list with the user subscriptions') and adds distinguishing detail: descending sort by user creation date, 20-per-page pagination, and AND-combination of query params. This clearly separates it from the many other get_* lookup siblings without needing to inspect the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('safe to call speculatively for lookups and reporting') and when-not-to-use ('Not for changing anything') are both present. The alternative is referenced only by category ('the matching 🟡 write tool') rather than by a named sibling tool ID, and no matching write-subscription sibling appears in the tool list, so the pointer is slightly unactionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag non-readonly and non-idempotent; the description reinforces and expands with concrete context: repeated calls can duplicate the effect, auth is injected server-side so the model never supplies tokens, calls are throttled under LearnWorlds' 30-per-10s cap and retried on 429/5xx, and non-2xx statuses surface as tool errors with 401/403/404/422 mappings. No contradiction with annotations — the write claim aligns with readOnlyHint=false and the non-idempotency claim aligns with idempotentHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Labeled sections (Behavior, Parameters, Returns, Use when) with the verb and endpoint front-loaded make this highly scannable. It runs longer than average, but every section carries actionable information — idempotency, auth, throttling, error mapping — so the length is justified rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no output schema and a nested body, the description closes nearly every gap: side effects in the live school, non-idempotency, auth handling, rate limits, exact return shape (HTTP status + JSON body), and error semantics. The only minor omission is that the pre-check read tool is left generic ('a 🟢 read tool') rather than naming get_affiliates, but this does not meaningfully impair an agent's ability to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents id and the nested body fields well, but the body object itself has an empty description (50% top-level coverage). The description compensates for exactly that gap by disclosing that the whole payload goes in the single body argument, is forwarded verbatim, and is in practice required even though the spec marks it optional — genuinely useful nuance the schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: making a user an affiliate, backed by the explicit endpoint POST /v2/affiliates/{id}. It is unmistakably distinct from the many get_* affiliate siblings because it is the only write operation among them, and it visibly differentiates itself from the related read tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit activation condition ('Use when: only when the user asked to create this') and a required precondition (verify the target exists and is not already an affiliate with a 🟢 read tool). It names related affiliate tools but stops short of mapping each alternative to a specific condition, so the when-not logic is largely implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), the description richly elaborates: it explains what non-idempotence concretely means ('a repeated call can duplicate the effect'), discloses that auth is injected server-side and never by the model, documents the 30-per-10s throttle with retry on 429/5xx, and specifies exact return/error semantics (HTTP status prefix, non-2xx surfacing as tool errors with 401/403/404/422 meanings). No claims contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but tightly organized with labeled sections (Behavior, Parameters, Returns, Use when) and front-loaded with the HTTP verb and endpoint. Every sentence carries operational value for a write tool with no output schema — idempotence, auth, throttling, error mapping, parameter forwarding, and preconditions — so the length is proportionate to the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description provides a complete calling contract: the response shape (array of created coupon resources), the HTTP-status return format, error-payload behavior per status code, auth/rate-limit handling, the body-required caveat, and read-tool prechecks. Nothing an agent needs to invoke this tool correctly or interpret its result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% and the body parameter's own schema description is empty, so the description compensates by resolving the critical trap: 'the whole JSON payload goes in the single `body` argument, forwarded verbatim (the spec leaves `body` optional, but this endpoint expects one).' This prevents an agent from omitting body because it is not top-level required. Nested fields (prefix, expires, quantity) already have adequate schema descriptions, so no extra detail is needed there.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise operation signature ('WRITE · creates data · POST /v2/promotions/{id}/coupons-bulk') and states 'Bulk create coupons in a promotion' — a specific verb, resource, and endpoint. The bulk-vs-single distinction from sibling create_coupon_promotion is clear from the title, the word 'Bulk', and the enumerated related Promotions tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section gives an explicit trigger — 'only when the user asked to create this' — plus a precondition to verify with a read tool that the target exists and the record is not already there. Related alternatives are listed (get_promotion, create_coupon_promotion, create_promotion, get_coupon_usage, get_promotions), but there is no explicit when-not rule such as 'for a single coupon use create_coupon_promotion instead,' so the alternative-selection logic 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, it discloses non-idempotency with the duplicate-effect consequence, server-side auth injection, throttling to the 30-per-10s cap, retry on 429/5xx, and the exact non-2xx error payload behavior. These are substantive behavioral details not present in the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into front-loaded, labeled sections (Behavior, Parameters, Returns, Use when) with no wasted sentences. It avoids repeating schema field details and packs each line with operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description covers response shape, status-return behavior, error mapping, auth, throttling, retries, and preconditions. For a mutating endpoint with one nested body parameter, this is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The nested body schema already documents every field (100% coverage), so the baseline is 3. The description adds important semantics: the whole payload goes in the single body argument, is forwarded verbatim, and while the schema marks body optional, this endpoint requires it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: 'Create a new Promotion without coupons' plus the exact POST endpoint and response. The 'without coupons' qualifier differentiates it from the sibling create_coupon_promotion / create_coupons_promotion_bulk tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit 'Use when' rule ('only when the user asked to create this') and advises verifying existence with a read tool first. Related Promotions tools are listed, but the description does not crisply state when to choose each alternative, so some routing inference remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by explaining non-idempotency, live-school mutation risk, server-side auth injection, throttling under 30-per-10s, retry behavior on 429/5xx, and detailed HTTP error mappings. This fully aligns with the annotations and adds substantial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections (Behavior, Parameters, Returns, Use when) and front-loaded with a clear one-line summary. No sentence is wasted; the length is justified by the operational caveats and error semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description covers the return format, error behavior, prerequisites, related tools, auth, throttling, and non-idempotency. The only remaining details are the body fields themselves, which are fully documented in the input schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the body schema already documents each field. The description adds important meaning by saying the entire payload goes in a single body argument, is forwarded verbatim, and that body is effectively required even though the spec marks it optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States clearly that the tool creates a new seat offering, with the endpoint POST /v2/seats and an explicit WRITE label. This distinguishes it from the related get/update/delete seat tools by naming the specific create operation and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a dedicated 'Use when' section saying to use this only when the user asked to create this, and advises checking with a read tool first. It names several related seat tools, though it does not explicitly say to use update_seat_offering for modifications, so it is slightly incomplete as an alternatives guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds substantial behavioral context: permanent removal with no undo, server-side auth injection, throttling and retry policy, expected success status codes, and detailed non-2xx error semantics. This goes well beyond what annotations provide and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with a destructive warning and clear verb. Each section—behavior, returns, use-when, related tools—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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description fully covers return values, error handling, prerequisites, safety confirmation, rate limiting, retries, and alternatives. An agent has everything needed to invoke this tool correctly and safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single 'id' parameter, so the schema already documents the parameter adequately. The description adds only a passing reference to 'provided certificate id,' which is minimally helpful but not necessary given the schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('deletes'), a specific resource ('certificate'), and the HTTP endpoint, and clarifies that it revokes/invalidates by permanently deleting. It also distinguishes itself from related certificate tools, so an agent can tell it apart from update_certificate_reissue and get_certificates without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' guidance is provided: only after the user confirms removal. It also names the alternatives for less destructive actions ('matching 🟡 update or unenroll tool') and lists related certificate tools, giving clear routing decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses permanent deletion with no undo, server-side auth injection, throttling to LearnWorlds' 30-per-10s cap, retry behavior on 429/5xx, and error-mapping details. This is rich behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with compact labeled sections: Behavior, Returns, Use when. Every sentence adds operational value, especially the warning, persistence semantics, and alternative routing, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with no output schema, the description fully covers what happens on success, what non-2xx responses mean, auth handling, rate limits, and when to use it. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the sole parameter 'id' as 'Unique identifier of the community space' with 100% coverage. The description only repeats this as 'provided space id' and adds no new format, source, or validation details, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a destructive warning and HTTP verb, then states 'Deletes the community space specified by the provided space id.' This is a specific verb + resource statement and is clearly differentiated from the related update and unenroll operations mentioned later.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: only after the user confirms the removal' and directs the agent to the update/unenroll tools for non-destructive alternatives. This leaves no ambiguity about when this destructive tool should be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses meaningful behavioral details beyond the annotations: read-only lookup against the live school, no creation or mutation, server-side auth injection, throttling under LearnWorlds' 30-per-10s cap, retry behavior on 429/5xx, and exact error status semantics. This is strong additional transparency and does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear scannable sections: endpoint, behavior, returns, and use-when guidance. Every sentence adds useful information, and the key read-only nature is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 no output schema, the description covers endpoint path, invocation behavior, return format, error semantics, authentication, throttling, and alternatives. Nothing an agent needs to decide whether and how to call this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter is already described as 'Unique identifier of the community space'. The description adds modest context by saying the resource is 'specified by the provided space id', but it does not add substantial new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get a community space' with the endpoint 'GET /v2/community/spaces/{id}', and clarifies it returns information for the space specified by the provided id. This distinguishes it from the plural list tool get_community_spaces and from the related write tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool: 'safe to call speculatively for lookups and reporting', and when not to: 'Not for changing anything — use the matching write tool.' It even names several related Community tools, giving the agent clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds meaningful behavioral context: it performs a read-only lookup against the live school, creates/changes/deletes nothing, injects auth server-side, throttles under the rate cap, retries on 429/5xx, and explains error statuses. This exceeds what the annotations alone convey and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the tool's purpose, then uses labeled sections for Behavior, Returns, and Use when. Every sentence adds value, including the rate-limit and retry details, and there is no redundant repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, one parameter, and no output schema, the description is complete: it explains the return format, pagination and sorting, error semantics, auth handling, rate limiting, and read-only safety. An agent has enough information to invoke it correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the single parameter, describing it as 'Affiliate Id or email (encoded string)', so the description does not need to add much. The description adds minor context by framing it as 'the provided affiliate' and showing the endpoint path, but the schema already carries the semantic weight. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Get completed affiliate payouts') and immediately clarifies scope: all completed payouts related to a given affiliate. It also distinguishes the tool from sibling payout tools by naming 'completed' and listing related Affiliates tools, so an agent can tell it apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('safe to call speculatively for lookups and reporting') and when not to ('Not for changing anything — use the matching 🟡 write tool'). It also names related Affiliates tools as alternatives, including get_due_affiliate_payouts and get_upcoming_affiliate_payouts, giving clear routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial context beyond them: auth is injected server-side and never by the model, calls are throttled to LearnWorlds' 30-per-10s cap with retries on 429/5xx, and the exact return/error format is specified (HTTP status + JSON body, with 401/403/404/422 semantics). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a READ-ONLY · GET badge and a one-sentence summary, then organized into Behavior, Returns, and Use-when sections. Every sentence earns its place: auth, rate limits, error codes, and routing to the write tool appear exactly once with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is complete: it covers the parameter, safety profile, auth handling, throttling, return shape, error surface, and sibling routing. The absence of an output schema is adequately compensated by the explicit return-format and error-code explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline of 3 applies with the schema doing the heavy lifting. The description's endpoint path /v2/courses/{id}/contents confirms the id identifies the course to read, but adds no format or syntax details beyond the schema's 'Course title Id'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+scope in the opening sentence: 'Get contents of a course... specified by the provided course id. Includes sections and learning activities.' Distinguishes from siblings by naming related Courses tools (create_course_section, get_course, get_course_grades, get_users_per_course, update_course) and pointing to the matching write tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes an explicit 'Use when:' section: 'safe to call speculatively for lookups and reporting. Not for changing anything — use the matching 🟡 write tool.' This provides both affirmative context and an exclusion with a named alternative, fully exceeding the requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses server-side auth injection, rate-limit throttling, retry behavior on 429/5xx, and error-code semantics for 401/403/404/422. This gives the agent a full behavioral model of the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections for behavior, returns, and usage. It is dense but every section provides operationally relevant information, and the read-only warning is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only lookup with strong annotations, the description covers everything an agent needs: safe usage, authentication model, throttling, error handling, and response format. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, id, is fully documented in the schema as 'Affiliate Id or email (encoded string)'. The description does not add meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact resource (due affiliate payouts), the HTTP endpoint, and the read-only lookup behavior. It also names sibling affiliate payout tools, making the distinction between due, completed, and upcoming payouts clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use this tool (safe speculative lookups and reporting) and when not to (mutating operations should use the write tool). It also lists related Affiliates tools, giving the agent concrete routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by explaining that auth is injected server-side, calls are throttled to LearnWorlds' 30-per-10s cap, retries happen on 429/5xx, and non-2xx responses surface as tool errors with specific status meanings. This is rich behavioral context the agent would not otherwise know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections, front-loaded with a READ-ONLY indicator, and every sentence conveys actionable information. Despite covering safety, auth, throttling, return format, error behavior, and usage context, it remains tight and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description compensates by explaining the return format and error semantics. It also covers authentication constraints, rate limiting, retry behavior, and when to use the tool. Nothing essential is missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the one parameter already has a clear description ('Payment Id or Transaction id'). The description mentions 'provided payment id' but adds no meaningful 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get payment' and 'Returns information about the payment specified by the provided payment id.' It clearly identifies this as a single-record lookup, distinguishing it from the plural sibling get_payments and the related get_invoice_link_per_payment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use when: safe to call speculatively for lookups and reporting' and 'Not for changing anything — use the matching 🟡 write tool.' It also names related Payments tools, giving the agent clear routing guidance versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is consistent with those. It adds substantial context beyond the annotations: auth is 'injected server-side, never by the model', calls are 'throttled to stay under LearnWorlds' 30-per-10s cap and retried on 429/5xx', and non-2xx replies are mapped to 401/403/404/422 meanings. This gives the agent a realistic model of failure modes and operational constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but rigorously organized into labeled sections (Behavior, Returns, Use when) and front-loaded with the 🟢 READ-ONLY badge and endpoint. Every sentence earns its place: auth injection, rate-limit behavior, retry policy, and error semantics are all operational facts an agent needs. There is no filler or repetition of annotation data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter, read-only lookup, nothing needed for correct invocation is missing. The schema covers the parameter fully, annotations cover the safety profile, and because there is no output schema, the description compensates by specifying the return shape ('HTTP <status> followed by the LearnWorlds JSON response body') and how errors surface as tool errors. The tool is complete as documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single required parameter id is documented as 'Promotion Id' in the schema. The description only restates that the tool targets 'the promotion specified by the provided promotion id' without adding format, validation, or usage nuance. Per the high-coverage baseline rule, a 3 is appropriate since the schema carries the parameter-documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description pairs a specific verb with a specific resource: 'Get promotion. Returns the promotion specified by the provided promotion id.' The endpoint path (GET /v2/promotions/{id}) and the contrast with the sibling list tool get_promotions make the tool's role unmistakable. It is clearly differentiated from create_promotion (write) and get_promotions (list) without needing to open schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use when: safe to call speculatively for lookups and reporting. Not for changing anything — use the matching 🟡 write tool.' This states both the positive context and the exclusion, and it names concrete alternatives including create_coupons_promotion_bulk, create_coupon_promotion, create_promotion, get_coupon_usage, and get_promotions. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, but the description goes well beyond them: it discloses server-side auth injection, throttling under LearnWorlds' 30-per-10s cap, retry behavior on 429/5xx, and the exact error semantics for 401/403/404/422. Nothing contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections (Behavior, Returns, Use when, Related) and front-loaded with the read-only indicator and endpoint. Each sentence adds distinct information with no filler or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with no output schema, the description covers everything needed to invoke it correctly: scope, return format, error handling, safety profile, throttling behavior, and usage guidance. There are no meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with 'Promotion Id' documented, so the schema carries the parameter meaning. The description adds only that the pid selects which promotion's coupons are returned, which is marginal added value; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Returns all coupons for the promotion specified by the provided promotion id.' It clearly identifies the endpoint and the parameter that selects the result set, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' guidance says it is safe for speculative lookups and reporting, and states what it is not for: 'Not for changing anything — use the matching 🟡 write tool.' It also names the related Promotions tools, helping an agent route to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description discloses auth injection server-side, throttling to LearnWorlds' 30-per-10s cap, retry behavior on 429/5xx, and the precise error mapping for non-2xx responses. It also confirms 'creates, changes and deletes nothing,' which aligns with and enriches 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the tool's purpose, then organized into Behavior, Returns, and Use when sections. Every sentence adds distinct value—endpoint, safety, auth, throttling, errors, and usage guidance—with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list endpoint with one optional parameter and no output schema, the description covers everything an agent needs: purpose, behavioral guarantees, auth, rate limits, return format, error handling, and recommended usage. No important context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the single optional parameter is already fully documented with an enum and 'Filter by event type.' The description only restates the enum values in prose and does not add semantics beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get school events' and specifies the resource with an HTTP endpoint, then enumerates the exact event types returned (course drip feed, file assignment, live session). This is a specific verb+resource that is easy to distinguish from sibling tools like get_event_logs or get_courses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when: safe to call speculatively for lookups and reporting' and provides a clear exclusion: 'Not for changing anything — use the matching 🟡 write tool.' This gives the agent both a positive use case and a when-not-to-use condition, even though the write tool isn't named directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description goes well beyond these by revealing auth injection is server-side, calls are throttled under a 30-per-10s cap with retry on 429/5xx, and non-2xx responses map to specific error statuses. It also clarifies the return format since there is no output schema. There is no contradiction with 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections: purpose, behavior, returns, and usage guidance. It is longer than minimal but every sentence adds value—auth, rate limits, error handling, and alternatives are all relevant for correct invocation. The key read-only and GET details are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 parameters, full schema coverage, and rich annotations, the description covers everything an agent needs: what it does, return format, error semantics, auth behavior, rate limits, and when to use it versus alternatives. There is no output schema, but the description explicitly explains the response structure, making the definition complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the schema already documents both `id` (User Id or email) and `include_suspended` (filter flag with default false). The description does not add parameter-specific meaning beyond saying 'by the provided user id,' so it stays at the baseline 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get a user. Returns the user specified by the provided user id.' Combined with the read-only indicator and GET path, it is unmistakable what this tool does. It further distinguishes itself from sibling tools by explicitly noting it is not for changing anything and listing related Users tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly states when to call it: 'safe to call speculatively for lookups and reporting.' It also provides a clear exclusion: 'Not for changing anything — use the matching 🟡 write tool.' It names related Users tools, giving concrete alternatives for user-specific data, so an agent can decide between this and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint/idempotentHint/destructiveHint annotations: explains server-side auth injection, throttling to LearnWorlds' 30-per-10s cap, retry behavior on 429/5xx, default pagination limit of 20, and detailed error response handling with HTTP status and API payload meanings. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with short labeled sections (Behavior, Parameters, Returns, Use when), and every sentence adds useful information. The endpoint and READ-ONLY marker are front-loaded. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers return format, errors, auth, throttling, and pagination. All essential aspects of calling a read-only paginated API are present, and the related tools are named for further routing. Nothing critical is missing for an agent to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 adds functional meaning by explaining 'results are paged — walk them with page and size each page with items_per_page', and mentions the default limit of 20. This is a modest improvement over the schema's field descriptions, enough to merit a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action and resource: 'Get user progress' for a specified user across all enrolled courses, including per-learning-activity breakdown. It distinguishes itself from sibling tools like get_user_progress_per_course by scoping to all courses and by being read-only, so an agent can tell it apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'safe to call speculatively for lookups and reporting', 'Not for changing anything — use the matching 🟡 write tool', and names related reporting tools. It lacks a precise condition for choosing get_user_progress_per_course over this tool, but the read-only vs. write split and general context are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, and non-destructive hints, and the description adds substantial behavior beyond that: auth is injected server-side, calls are throttled under LearnWorlds' 30-per-10s cap and retried on 429/5xx, and non-2xx responses surface as tool errors with status and API error payload. This gives an agent realistic expectations for safety, failures, and throttling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Behavior, Returns, Use when) and every section adds practical information. It is longer than a minimal description, but the added length is justified by the lack of an output schema and the need to convey auth, rate limits, and error behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a read-only list tool with no output schema: it explains what it returns, the ordering of results, how errors appear, auth constraints, rate-limit behavior, and when it is safe to use. Nothing an agent needs to invoke or interpret this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both role_id and access_level already have clear descriptions, examples, and enum values. The description does not add extra parameter-level semantics, but because the schema fully documents both parameters, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Get all user roles', 'GET /v2/user-roles') and clearly states scope: all user roles of the school, sorted alphabetically by title. This makes the tool's purpose unambiguous and distinct from sibling tools like get_user_role_user or get_user_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it: 'safe to call speculatively for lookups and reporting.' It also states what not to use it for — 'Not for changing anything — use the matching 🟡 write tool' — which gives clear routing guidance without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds substantial context: server-side auth injection, throttling with retries on 429/5xx, pagination limits, and a clear mapping of non-2xx responses to tool errors. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, front-loaded purpose, and no filler. Every sentence adds operational value: endpoint, behavior, auth, rate limits, return format, errors, and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by explaining the return format, error payloads, authentication, throttling, pagination, and scope. It gives an agent everything needed to call the tool safely and interpret failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that results are paginated and should be walked with 'page', and it clarifies the 20-users-per-page limit, which is not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get all users by product'), gives the endpoint GET /v2/users/by-product, and defines exactly what is retrieved: users with access to the specified product. It also adds sorting and pagination detail, making it easy to distinguish from product-oriented siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool ('safe to call speculatively for lookups and reporting') and when not to use it for mutations, directing the agent to the matching write tool. It lists related Users tools but does not precisely explain when to prefer this over similarly named tools like get_products_user or get_users_per_course.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes well beyond annotations: it states auth is injected server-side, calls are throttled under a 30-per-10s cap and retried on 429/5xx, results are sorted with newest first, default pagination limit is 20, and non-2xx replies surface as tool errors with specific HTTP status meanings. No contradiction with readOnlyHint, idempotentHint, or destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with labeled sections (Behavior, Parameters, Returns, Use when) and is front-loaded with a one-line summary. While slightly longer than minimal, every section contributes useful information, especially error handling and usage context, with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description thoroughly covers return format, error semantics, pagination, ordering, authentication, and rate limiting. It also provides sibling context and clear guidance for safe calling. Nothing essential is missing for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 minimal semantic value for the parameters: it mentions walking pages via `page` and the default page size, but the schema already explains both parameters well, including page-number behavior. No significant compensation for gaps is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'Get users of a user group' and 'Retrieves all the users who are members of the user group specified by the provided group id.' It distinguishes this from sibling tools like get_user_group (group details) and add_user_user_group/remove_user_user_group (mutating membership). The resource and verb are both explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly says it is safe for speculative lookups and reporting, and warns against using it for changes, pointing to the matching write tool. It also lists related User groups tools, giving an agent clear routing guidance and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses that the action is permanent, that auth is injected server-side and never by the model, that calls are throttled/retried, and exactly what HTTP statuses and error payloads to expect. This goes far beyond the annotations and gives the agent essential expectations for a destructive call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: destructive warning, endpoint, behavior, server-side auth, throttling/retry, return semantics, error mapping, and usage guidance. It is front-loaded with the most important warning and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter destructive tool with no output schema, the description is complete: it explains what happens, what the response looks like, what errors mean, how auth works, and when the tool should be used. An agent has enough information to invoke it correctly and anticipate failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description only restates that the user is identified by uid and the space by id, adding no extra format, constraints, or behavior beyond what the schema provides. A baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear, specific action: 'Remove a user from a community space', and explicitly names the resource and identifiers involved. It also differentiates itself from sibling tools like remove_user_seat and remove_user_user_group by scoping to community spaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('only after the user confirms the removal') and when not to ('To merely revoke access or deactivate, use the matching update or unenroll tool instead'). It also lists related Community tools as context, giving an agent clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes far beyond the annotations: discloses permanence ('no undo from this server'), server-side auth injection, throttling under LearnWorlds' 30-per-10s cap, retry on 429/5xx, expected success codes (200/204 with usually empty body), and a full error-to-meaning mapping (401/403/404/422). No contradiction with destructiveHint/readOnlyHint/idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and front-loaded: the destructive warning and endpoint headline come first, followed by a one-line summary and clearly labeled Behavior/Returns/Use-when sections. Every sentence carries distinct value (permanence, auth, throttling, error semantics, usage conditions) with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive 2-parameter tool with no output schema, the description is complete: it covers return values and error payloads, auth requirements, rate-limit behavior, permanence caveats, and alternative routing. An agent has everything needed to decide whether to invoke it and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (id as user group identifier, uid as user id or encoded email). The description's URL path hints at the parameter roles, but it adds no semantic detail beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Remove a user from a user group') and reinforces it with the HTTP endpoint DELETE /v2/user_groups/{id}/users/{uid}. It further distinguishes itself from siblings by naming the related User groups tools (add_user_user_group, deletes_user_group, etc.) and contrasting with update/unenroll tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' guidance: only after the user confirms removal. It also states when NOT to use it ('To merely revoke access or deactivate, use the matching 🟡 update or unenroll tool instead'), giving the agent a concrete decision rule against alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by explaining idempotency, server-side auth injection, throttling under LearnWorlds' rate cap, retry behavior on 429/5xx, the exact response format, and per-status error semantics. This gives the agent a complete behavioral model for invoking the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every section earns its place: behavior, auth, parameters, returns, and usage guidance are all clearly labeled and front-loaded. The structure makes it easy for an agent to scan and extract relevant facts quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description fully covers return values, error handling, rate limits, authentication expectations, idempotency, and when to use the tool versus creating a record. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema coverage, the description compensates by clarifying that the entire JSON payload must be sent in the single `body` argument and that even though the spec marks `body` optional, this endpoint expects one. The schema already documents the id and nested body properties well, so this additional context is valuable and sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: updates the tags of a user identified by user ID or email via PUT /v2/users/{id}/tags. It also specifies the endpoint's response, which distinguishes this tool from generic user tools like update_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use the tool only when changing an existing record, advises reading the record first to avoid unintended overwrites, and recommends using a create tool when the record does not exist. It also lists related Users tools, though it does not explicitly contrast this with the sibling update_user tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description richly discloses behavior: it is a non-idempotent write that can duplicate effects, auth is injected server-side, calls are throttled and retried, and non-2xx responses surface as tool errors with specific status meanings. This fully compensates for and expands on the annotation hints. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections for behavior, parameters, returns, errors, and usage. It is dense and information-rich, though the opening two sentences repeat essentially the same point, which is minor redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description thoroughly covers return values, error statuses, auth, throttling, idempotency, and when to use the tool. It provides everything an agent needs to invoke this tool correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 important practical meaning: the entire payload goes in the single body argument, forwarded verbatim, and although the spec marks body optional, the endpoint expects one. This helps the agent avoid misusing the body parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds or invites users to a community space, with a specific verb, resource, and the conditional behavior based on is_invitation_required. It distinguishes itself from sibling tools like get_users_community_space and remove_user_community_space. The only minor issue is a slight redundancy between the first two sentences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to use this tool ('only when the user asked to create this') and advises checking with a read tool first to verify the target exists and the record is not already present. It also names related community tools, giving clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses non-idempotency ('a repeated call can duplicate the effect'), live-world mutation, server-side auth injection, throttling, and error/status behavior. This goes well beyond what the annotations alone provide and remains consistent with readOnlyHint=false and idempotentHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-structured into labeled sections (Behavior, Parameters, Returns, Use when) and front-loads the key information. Minor redundancy exists, such as both 'creates data' and 'Creates a new course' earlier in the text, but it remains efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers creation semantics, non-idempotence, authentication, rate limiting, error handling, parameter forwarding, and when to use it. Nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, including descriptions for nested fields, so the schema already documents the body contents. The description adds valuable semantics: the entire payload goes in the single 'body' argument, is forwarded verbatim, and although the spec marks body optional, this endpoint expects one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Creates a new course' via POST /v2/courses, and identifies the response as the created Course resource. This clearly distinguishes it from sibling tools like get_course, update_course, and create_course_section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: only when the user asked to create this,' and instructs to check with a read tool that the target exists and the record is not already there. It also names related Courses tools, giving the agent concrete guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: non-idempotence and duplicate-effect risk (reinforcing idempotentHint=false), server-side auth injection ('never by the model'), throttling under a 30-per-10s cap with 429/5xx retries, and a full error-surface mapping (401/403/404/422). No contradiction with annotations; readOnlyHint=false, idempotentHint=false are consistent with the WRITE and 'not idempotent' statements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with a scannable '🟡 WRITE · creates data · POST /v2/users' header followed by clearly labeled Behavior/Parameters/Returns/Use-when sections. Slightly redundant ('creates a new user' appears alongside 'creates a record or triggers an action'), but every labeled block earns its place given the auth, throttling, and error details it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a single-parameter create tool with no output schema: it covers what happens on success (created User resource), what returns look like ('HTTP <status>' plus JSON body), how errors surface, who authenticates, rate-limit behavior, and the required pre-check. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds a crucial caveat: the whole payload goes in the single `body` argument forwarded verbatim, and although the spec marks `body` optional, this endpoint expects one. That directly compensates for the schema reporting 0 required parameters and prevents a call with an empty body.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ('Creates a new user'), the HTTP endpoint, and explicitly labels it WRITE. The dedicated 'Use when' section only-when-asked-to-create plus the related Users tools list helps an agent tell it apart from get_user/update_user/suspend_user in a large sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it ('only when the user asked to create this') and gives a concrete pre-flight procedure: verify with a 🟢 read tool that the target exists and the record isn't already there. Naming the related Users tools provides the alternative routing an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations: it explains the real-world effect ('creates a record or triggers an action in the live school'), the non-idempotency consequence (duplicate effect on repeated call), server-side auth injection, 30-per-10s throttling with 429/5xx retry, and detailed error semantics (401/403/404/422 mapped to meanings). This adds substantial behavioral context that annotations alone do not convey, and it is fully consistent with readOnlyHint=false, idempotentHint=false, and destructiveHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but the tool is genuinely complex (auth, throttling, non-idempotency, error handling, no output schema), and each labeled section (Behavior, Parameters, Returns, Use when) earns its place. The front-loaded '🟡 WRITE · creates data · POST' line gives an immediate orientation, and the structured format keeps dense information scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-idempotent write tool with no output schema, the description is complete: it covers return format (HTTP status + response body), failure behavior, authentication, rate limits, retry policy, required pre-checks, and related tools. Nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 genuine value by clarifying that the entire JSON payload goes in the single 'body' argument forwarded verbatim and that although the spec marks body optional, the endpoint expects one — a caveat that could prevent an agent from omitting a required payload. This is a meaningful semantic addition beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — "Enroll user to product" — and specifies the product scope (course, bundle, manual subscription) with the exact POST endpoint. It clearly differentiates from the sibling unenroll_user_product and names the other related Users tools, so an agent can tell them apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly restricts invocation: 'only when the user asked to create this,' and gives a concrete precondition — verify with a 🟢 read tool that the target exists and the record is not already there. It also lists the relevant sibling tools (unenroll_user_product, get_courses_enrollments_user, get_products_user, get_seat_offerings_that_user_is_member, get_user), providing both timing and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent annotations, the description discloses sorting order, 20-per-page pagination, AND-combining of filters, server-side auth injection, 30-per-10s throttle with retry on 429/5xx, and detailed error status semantics. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with labeled sections (Behavior, Parameters, Returns, Use when) and front-loaded read-only/GET marker. A minor redundancy in 'Get certificates. Returns a list with certificates' keeps it from being perfectly concise, but every section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a list endpoint with no output schema: it explains pagination, filtering, auth, rate limits, error mapping, and relationship to sibling tools, so an agent can invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers all parameters with descriptions (100% coverage). The description adds the AND operator behavior across query params, the 'at least one query parameter required' rule, and directs the agent to page through results using `page`, which enhances but does not duplicate the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get certificates. Returns a list with certificates'), identifies the HTTP endpoint, and distinguishes itself from the certificate write tools by naming them. Clear and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides a 'Use when' section ('safe to call speculatively for lookups and reporting'), a when-not ('Not for changing anything — use the matching 🟡 write tool'), and names alternate certificate tools. Also states the requirement that at least one query parameter be provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states read-only behavior, that auth is injected server-side, that calls are throttled and retried on 429/5xx, and how non-2xx responses surface as tool errors. This adds meaningful behavioral context beyond the annotations, and does not contradict readOnlyHint or idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded with the endpoint and read-only signal. It is slightly redundant with 'read-only' appearing both in the header and the Behavior section, but every other sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six optional parameters and no output schema, the description covers the essential call semantics: filtering behavior, sorting, pagination, authentication, throttling, retries, and error responses. An agent has enough information to invoke the tool correctly and understand the result envelope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by explaining that multiple query params are combined with an AND operator and that pagination is done by walking pages with `page` and sizing with `items_per_page`. This goes beyond the individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get community posts' via GET /v2/community/posts. It clearly explains what the returned list contains, the sort order, and pagination, which distinguishes it from singular/other community tools like get_community_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly provides a 'Use when' section: 'safe to call speculatively for lookups and reporting.' It also states what the tool is not for: 'Not for changing anything — use the matching 🟡 write tool,' and lists related Community tools, giving the agent clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by explaining that auth is injected server-side, calls are throttled under LearnWorlds' 30-per-10s cap, retries occur on 429/5xx, and non-2xx responses surface as tool errors with specific status meanings. This adds substantial behavioral context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-structured with clear sections: behavior, returns, usage, and related tools. Each section adds meaningful information. Some redundancy exists with the annotations, but overall it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description explains the return format as 'HTTP <status> followed by the LearnWorlds JSON response body' and details error behavior. For a zero-parameter read-only lookup, this is complete enough for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is complete and there is nothing to document. The description adds value by confirming the tool returns all user segments without filters. A baseline of 4 is appropriate for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get user segments' and 'Returns a list of all user segments in the school.' It clearly names the operation and scope. It also contrasts with write tools, though it does not explicitly differentiate from the similarly named sibling get_users_segment, which may be a singular variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Use when: safe to call speculatively for lookups and reporting. Not for changing anything — use the matching 🟡 write tool.' It also lists related Users tools, helping an agent select among alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/idempotent annotations, the description adds rich context: auth is injected server-side and never by the model, calls are throttled to respect a 30-per-10s cap and retried on 429/5xx, results are sorted with newest first, and default pagination is 20. This fully discloses operational behavior and side effects (none).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: method summary, behavior, parameters, returns/errors, and usage guidance. It is front-loaded with a one-line summary and uses clear section labels, making it scannable and efficient despite its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 must carry the burden of explaining returns. It does state that it returns the LearnWorlds JSON response body and describes error semantics (401, 403, 404, 422). It does not detail the structure of the user objects in the response, which is a minor gap for a list endpoint, but overall the description is comprehensive for an agent to invoke it safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds value by explaining the pagination interaction ('walk them with page and size each page with items_per_page') and noting the default page size of 20, which is not evident from the schema alone. It doesn't deeply explore the API's response fields, but for parameters it is above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with an explicit method and resource ('GET /v2/courses/{id}/users') and a clear statement: 'Retrieves all the users enrolled in the course specified by the provided course id.' This is a specific verb+resource pair that is unambiguous and distinct from sibling list tools like get_users or get_user_progress_per_course.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly states when to call it ('safe to call speculatively for lookups and reporting') and gives a clear exclusion: 'Not for changing anything — use the matching 🟡 write tool.' It also lists related Courses tools, helping the agent select among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses non-idempotency consequences (duplicate effects on repeated calls), server-side auth injection (the model must never supply auth), throttling under LearnWorlds' 30-per-10s cap with retries on 429/5xx, and full error-code semantics for 401/403/404/422. These details directly shape agent behavior and are not derivable from annotations or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but every labeled section (Behavior, Parameters, Returns, Use when) carries essential information for a mutation tool with no output schema. It is front-loaded with the WRITE status, endpoint, and non-idempotency warning before descending into detail; only minor trimming would be possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, the description fully explains return values (HTTP status followed by the JSON response body) and how errors surface as tool errors with status and API payload. Combined with the body-parameter caveat, auth/throttling notes, and usage pre-checks, there are no material gaps for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so id, cid, units, and send_course_complete_email are already well documented. The description adds one critical clarification: the entire payload goes in the single body argument forwarded verbatim, and although the spec marks body optional, this endpoint expects one — a caveat that prevents a foreseeable agent failure when following the schema naively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Updates the user's progress on a course or learning activity level as complete.' It clearly frames the operation as a WRITE action with the exact endpoint, and naming reset_user_progress as the related sibling makes its scope unmistakable even within the large sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section is explicitly prescriptive: use only when the user asked to create this, and first verify with a 🟢 read tool that the target exists and the record is not already there. It also points to reset_user_progress as the related alternative, giving the agent clear routing guidance between the two progress-mutation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by explaining PUT replacement semantics, idempotency, server-side auth injection, throttling/retry behavior, return format, and specific error statuses. All of this is consistent with the annotations: readOnlyHint=false, idempotentHint=true, destructiveHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections and packs in dense useful information without fluff. It is somewhat long, but the complexity of the endpoint justifies the length. Front-loads the core purpose and HTTP method before details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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, the description covers request semantics, response format, error handling, authentication, rate limits, and usage strategy. The related sibling tools are named, and the agent has enough context to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies that the entire JSON payload goes into the `body` argument and is forwarded verbatim, and notes that despite the spec marking `body` optional, this endpoint expects one. This adds meaningful guidance over the schema, which leaves `body`'s top-level description empty. The `id` parameter is straightforward from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates/reissues a certificate identified by its id, using PUT /v2/certificates/{id}. It explicitly differentiates itself from related certificate tools including delete_certificate_revoke_invalidate and get_certificates, and references the create tool as the alternative for records that do not exist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' guidance: only when the user wants to change an existing record. It instructs to read the record first before overwriting, and directs the agent to use the create tool if the record does not exist. This is strong, actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the annotations: idempotency is explicitly stated, auth injection is clarified as server-side, rate limiting and retry behavior are disclosed, and error mapping for 401/403/404/422 is fully documented. This is far beyond what the annotations alone communicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than minimal but well organized with labeled sections for Behavior, Parameters, Returns, and Use when. It is front-loaded with the core purpose and HTTP method, and the length is justified by the behavioral and error-handling details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with no output schema, this description covers everything needed: the request semantics, response format, error behavior, authentication model, rate limiting, idempotency, and when to choose this vs. the create tool. There is no obvious missing context that would cause an agent to misinvoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each parameter. The description adds real value by clarifying that the entire JSON payload goes into the single body argument and is forwarded verbatim, and by warning that although the spec marks body optional, this endpoint expects one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Updates the course specified by the provided course id.' The description clearly identifies this as a write/update operation and differentiates it from the create tool by saying 'use the create tool if it does not exist yet.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: only when the user asked to change an existing record' and instructs the agent to read the record first to avoid overwriting unintended fields. It also names the create tool as the alternative when the course does not exist, which is direct and practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnlyHint=false and idempotentHint=false, and the description enriches them substantially: it explains that repeated calls duplicate the effect, describes server-side auth injection (admin token + Lw-Client id, never by the model), discloses the 30-per-10s throttle with retry on 429/5xx, and details the response/error surface (HTTP status + body, plus specific meaning of 401/403/404/422). This is exactly the contextual depth a write tool needs. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: operation line, behavior, parameters, returns, and usage guidance are cleanly sectioned and front-loaded. There is no filler or repetition of schema content; each segment addresses a distinct concern an agent would have when invoking a mutating tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested-body write tool with no output schema, the description covers all essential angles: precondition verification via read tools, parameter passing mechanics, return format, error semantics, idempotency warning, and rate-limit behavior. The conditional collectionId rule is already documented in the schema, so the description need not repeat it. Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the nested body properties are individually documented, so the baseline is 3. The description adds genuine value beyond the schema by flagging a trap: 'the spec leaves body optional, but this endpoint expects one' and clarifying the payload is forwarded verbatim. This resolves an ambiguity that could otherwise cause a failed call, so it earns a 4 rather than baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Create a community space') plus the exact endpoint and method (POST /v2/community/spaces). It is unambiguous about what the tool does, and the 'Related Community tools' line explicitly situates it among siblings (add_invite_users_community_space, delete_community_space, get_community_space, etc.), so an agent can tell it apart without opening other schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section is explicit: 'only when the user asked to create this,' and it instructs the agent to check with a 🟢 read tool that the target exists and the record is not already present. This prevents duplicate-resource mistakes and goes beyond mere context to give actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the call is not idempotent and can duplicate effects, that auth is injected server-side, that calls are throttled and retried on 429/5xx, and that it operates on the live school. This is rich behavioral context consistent with annotations, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections: Behavior, Parameters, Returns, and Use when. Every sentence earns its place, and important operational facts are front-loaded without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description compensates by explaining the return format, error semantics and status codes, auth handling, rate-limit behavior, and pre-call checks. This is complete enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so individual field semantics are already documented. The description adds key operational meaning: the entire payload goes in a single `body` argument, is forwarded verbatim, and although the spec marks `body` optional, this endpoint expects one. That warning goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Creates a new user group' plus the endpoint 'POST /v2/user_groups'. It clearly identifies this as a create operation, and the related User groups tools list helps distinguish it from sibling read/update/delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Use when: only when the user asked to create this' and instructs the agent to check with a read tool that the target exists and is not already there. It also lists the related sibling tools, giving clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only/idempotent safety, and the description meaningfully goes beyond them: auth is injected server-side, calls are throttled to LearnWorlds' 30-per-10s cap and retried on 429/5xx, responses are paginated at 20 per page, and non-2xx behavior is specified with status codes and error payloads. This is substantial 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the method and read-only nature, then flows clearly through behavior, auth, parameters, return values, errors, and usage. Every section carries distinct operational information, and the structured labels make it easy to scan without being bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates well by explaining the HTTP status plus JSON response, error semantics for auth/permissions/not-found/invalid input, pagination mechanics, and ordering. It also places the tool among related affiliate siblings, giving an agent enough context to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, page, is already fully documented in the schema with a default and behavior. The description adds the practical guidance to 'walk them with page' and states the 20-per-page limit, which clarifies how to paginate beyond the schema's basic default-value note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific read operation (GET /v2/affiliates) that returns the school's affiliates, with ordering and pagination details. It is clearly distinct from sibling tools like get_affiliate_payments or get_leads_per_affiliate because those focus on per-affiliate derived data rather than the core affiliate list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it: 'safe to call speculatively for lookups and reporting.' It also says when not to use it — 'Not for changing anything — use the matching 🟡 write tool' — and lists related Affiliate tools, helping an agent route correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: it is a read-only lookup against the live school, creates/changes/deletes nothing, auth is injected server-side, calls are throttled and retried on 429/5xx, and responses are paginated with a limit of 20. It also explains error surfacing for non-2xx statuses. This far exceeds the already-supportive annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Behavior, Parameters, Returns, Use when) and front-loads the read-only nature and resource. While detailed, every section earns its place and no redundant filler is present. The formatting aids quick parsing by an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter, the description is fully complete: it covers pagination, ordering, response format, error handling, authentication, rate limiting, and intended usage. There is no output schema, but the description explicitly describes the return value shape, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the single `page` parameter with 100% coverage. The description adds complementary context by explaining that results are paged and that the agent should 'walk them with `page`,' reinforcing how the parameter should be used in practice. This adds modest value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get all bundles' and 'Returns a list of all bundles of the school.' It also clearly differentiates from the sibling get_bundle by indicating this returns all bundles in a paginated sorted list. The scoping and behavior are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it: 'safe to call speculatively for lookups and reporting.' It also instructs when not to use it: 'Not for changing anything — use the matching 🟡 write tool.' It names the related sibling get_bundle, giving the agent clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses read-only behavior, server-side auth injection, throttling under LearnWorlds' rate cap, retries on 429/5xx, the exact return format, and error handling for non-2xx responses. This far exceeds what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the READ-ONLY badge and HTTP method, then organized into clear Behavior, Returns, and Use when sections. Every sentence provides actionable operational information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter list tool, the description is fully complete: it states what is returned, ordering, authentication model, rate-limit behavior, retry policy, and error semantics. No output schema exists, so the description's return format explanation is essential and sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema already covers this completely. Per the baseline for 0-parameter tools, a score of 4 is appropriate; there is no parameter information missing, though the description also has no parameter-level detail to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Get all community collections') and clarifies it returns the school's community collections in sorted order. It is clearly distinct from sibling tools like get_community_spaces and get_community_posts because it targets collections specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it: 'safe to call speculatively for lookups and reporting.' It also tells the agent when not to use it ('Not for changing anything — use the matching 🟡 write tool') and lists related community tools as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint annotation by disclosing auth injection, throttling under LearnWorlds' 30-per-10s cap, retry behavior on 429/5xx, and the exact error surfacing semantics for 401/403/404/422. This is rich behavioral context an agent would otherwise not know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Organized into labeled sections (Behavior, Parameters, Returns, Use when) with front-loaded purpose. Every sentence contributes useful information and there is 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a read-only list tool with no output schema: it covers scope, ordering, pagination, auth, throttling, retries, status/error behavior, and usage guidance. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaningful procedural guidance on pagination: 'walk them with page and size each page with items_per_page,' which is not obvious from the schema alone. This small extra semantic justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Get community spaces. Returns a list with all community spaces of the school.' The plural 'spaces' plus 'all' distinguishes it from the singular sibling get_community_space, and the sorting detail adds concrete scope. The endpoint is also included.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: safe to call speculatively for lookups and reporting' and 'Not for changing anything — use the matching 🟡 write tool.' It also lists the related Community tools, giving the agent concrete alternatives for different operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint/idempotentHint annotations by disclosing server-side auth injection, throttling under LearnWorlds' rate cap, retry behavior on 429/5xx, sorted results, and a 50-per-page limit. It also explains how non-2xx responses surface as tool errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although longer than minimal, the description is cleanly sectioned into behavior, parameters, returns, and usage. Every sentence adds operational value, and the most important read-only scoping is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by explaining the return format, HTTP status behavior, error payload mapping, and pagination. Combined with the annotations and fully documented parameters, an agent has enough context to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the schema already documents page, access, and categories. The description adds practical pagination guidance—'walk them with page'—which clarifies how the page parameter should be used iteratively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get all courses' and clearly specifies the verb, resource, and scope: a read-only GET /v2/courses returning all courses of the school. It also clarifies pagination and ordering, distinguishing this bulk-list operation from the single-record get_course sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' guidance is provided: safe to call for lookups and reporting, not for mutations, with a pointer to the matching write tool. It also names related Courses tools and identifies the non-2xx error cases, giving an agent clear situational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark read-only/idempotent/non-destructive, and the description adds meaningful context: server-side auth injection, throttling under LearnWorlds' 30-per-10s cap, retry on 429/5xx, pagination behavior, and non-2xx error mapping. It reinforces rather than contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into compact labeled sections (Behavior, Parameters, Returns, Use when) and front-loads the read-only endpoint and core purpose. Despite covering auth, errors, pagination, and usage, it remains dense rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated read endpoint with no output schema, the description covers the endpoint, ordering, pagination, auth, rate limiting, error semantics, and when to call it. The only details left to the input schema are parameter-level descriptions, which are already complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 goes beyond it by explaining how to use pagination parameters ('walk them with page and size each page with items_per_page') and noting the 20-per-page default. It does not add much about 'users' or 'id', but those are adequately defined in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Get form responses' from /v2/forms/{id}/responses) and explains what it returns: all submitted responses, newest first, paginated. It also orients the agent against write siblings and related assessment tools, so it is easy to tell apart from the large sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when: safe to call speculatively for lookups and reporting' and 'Not for changing anything — use the matching 🟡 write tool' provide both positive and negative selection criteria. The related assessment tool names further steer the agent toward alternatives where appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent/non-destructive, but the description adds meaningful behavior beyond them: auth is injected server-side, calls are throttled under LearnWorlds' 30-per-10s cap and retried on 429/5xx, and non-2xx responses surface as tool errors with mapped HTTP status meanings. This is rich, actionable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clear labeled sections (Behavior, Parameters, Returns, Use when) and every sentence carries operational value. The read-only and endpoint info are front-loaded, and 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless-required read-only list tool with no output schema, the description fully covers return format, error behavior, pagination, filtering semantics, auth handling, rate limiting, and usage boundaries. The agent has everything needed to invoke and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented. The description adds valuable semantic context: multiple query params combine with AND logic, pagination is walked via page and sized via items_per_page, and default page size is 50. This goes beyond the schema's individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Get payments' returns a paginated list sorted by recency. It distinguishes itself from related payment tools by naming get_payment and get_invoice_link_per_payment as separate tools, and by emphasizing the list/pagination behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'safe to call speculatively for lookups and reporting,' and when not to: 'Not for changing anything — use the matching 🟡 write tool.' This gives the agent clear decision rules, especially against many sibling write tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations that already declare readOnly, idempotent, and non-destructive, the description adds concrete behavior: server-side auth injection, throttling and retry handling, sorted and paginated results, AND semantics for multiple filters, and detailed error response behavior. This is substantial added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections: Behavior, Parameters, Returns, Use when. It is longer than minimal, but every section carries distinct operational information needed for safe invocation, and the key purpose and constraints are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 and nine optional parameters, the description fully covers the essential context: what it returns, how pagination works, how filters behave, authentication, error handling, and when to use it. The parameter schema covers the rest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 100% of parameters, so the baseline is 3. The description adds valuable usage semantics: how to walk pages with `page` and `items_per_page`, how `cf__field_name` is translated to the original LearnWorlds parameter name, and that multiple filters combine with AND. This goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get all users' and clearly identifies the resource and scope: a list of all school users, sorted with newest first. It differentiates from siblings by naming related Users tools and specifying this is the read-only list endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' guidance states it is safe for speculative lookups and reporting, and explicitly says not to use it for changes, directing to the matching write tool. It also lists related Users tools, giving clear context for choosing this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description adds valuable behavior: 'read-only lookup against the live school; creates, changes and deletes nothing,' server-side auth injection, throttling under the 30-per-10s cap, retry on 429/5xx, and explicit error-surface behavior. This goes well beyond what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then uses short labeled sections for behavior, parameters, returns, and usage. Every sentence adds operational value—response format, error handling, auth, throttling, and when to use—without fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description explains the response envelope: 'HTTP <status> followed by the LearnWorlds JSON response body' and the behavior of non-2xx replies. It also covers pagination defaults, sorting, authentication, rate limits, and retry behavior, making the tool fully usable by an agent without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the two parameters, so the baseline is 3. The description adds meaningful extra semantics: pagination via `page`, default limit of 20 users per page, and sorting with newest users first. It does not repeat schema details and enriches the agent's understanding of how to use the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get all users of seat offering' and 'Retrieves all the users who are members of the seat offering specified by the provided seat offering id.' It clearly distinguishes this from sibling tools like get_specific_seat_offering and get_seat_offerings_that_user_is_member by stating it lists the members of one seat offering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use when: safe to call speculatively for lookups and reporting. Not for changing anything — use the matching 🟡 write tool.' It also names related seat-offering tools, giving the agent clear routing information versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint), the description discloses that auth is injected server-side, calls are throttled and retried, results are paginated at 20 per page, and non-2xx responses surface as tool errors with specific status interpretations. This meaningfully enriches the agent's understanding of runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well structured with clear headings (Behavior, Parameters, Returns, Use when) and front-loads the essential facts: read-only, HTTP endpoint, and core behavior. Every section earns its place, covering safety, pagination, auth, errors, and usage without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 only two simple parameters and no output schema, the description is complete: it defines the endpoint, result semantics, pagination, authentication, throttling, error handling, and intended use cases. No critical information is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the segment_id selects the segment and that pagination should be walked using the `page` parameter, reinforcing the schema's 'Filter by page number' with usage intent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get all users by segment' via GET /v2/users/by-segment. It clearly identifies the input (segment id), the result set (all users in that segment), and the ordering/pagination behavior, making it easy to distinguish from sibling tools like get_users or get_user_segments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it: 'safe to call speculatively for lookups and reporting.' It also says when not to use it: 'Not for changing anything — use the matching 🟡 write tool,' and lists related Users tools for context, giving an agent clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing non-idempotency, server-side auth injection, rate-limit throttling, retry behavior on 429/5xx, and detailed HTTP response/error semantics. This is especially valuable since annotations only provide basic hints like readOnlyHint=false and idempotentHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: it immediately states the write nature, endpoint, and purpose, then organizes behavior, parameters, returns, and usage into clear labeled sections. Each sentence provides actionable information without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a tool with no output schema. It covers the write behavior, idempotency implications, authentication model, rate limits, retries, HTTP return format, error mappings, and the necessary pre-call read check. The nested body schema handles the remaining payload details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the parameters and their nested fields. The description adds meaningful invocation guidance by clarifying that the entire JSON payload goes into the single body argument, is forwarded verbatim, and that the endpoint expects a body even though the schema marks it optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the operation: reviewing a user's assessment submission by updating grades and feedback and recalculating grades. It also labels the tool as a WRITE operation that creates data, and separates it from the related read-only Assessment tools get_assessment_responses and get_form_responses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: only when the user asked to create this review. It also instructs the agent to first check with a read tool that the target exists and the record is not already present, providing a clear precondition and guarding against duplicate actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the destructiveHint annotation by disclosing that removal is permanent with no undo from this server, that auth is injected server-side and never by the model, and that calls are throttled and retried on 429/5xx. It also explains non-2xx behavior and the meaning of specific error codes, which is critical for an irreversible mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every section earns its place: destructive warning, behavior, parameters, return/error handling, and usage guidance. It is clearly structured with labeled sections, making it easy for an agent to parse, and the most critical safety warning is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description is remarkably complete: it covers the HTTP method, permanence, auth, rate limiting, retries, expected success responses, error semantics, and when not to use it. The related-tool list also anchors it in the surrounding toolset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents both parameters, but the description adds important non-obvious semantics: the entire payload goes in the single body argument and is forwarded verbatim, and although the spec marks body optional, this endpoint expects one. It does not add much about the individual fields, but the schema already covers those via descriptions and an enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Unenroll user from a product' and clarifies it 'deletes' the enrollment record. It includes the exact endpoint and clearly distinguishes itself from the sibling enroll_user_product by describing both the opposite operation and its destructive nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use when: only after the user confirms the removal' and tells the agent to use the matching update or unenroll tool instead when the goal is merely revoking access or deactivating. It also lists related tools, giving the agent concrete routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by explaining that the endpoint replaces only the sent fields, is idempotent, has auth injected server-side, is throttled and retried on 429/5xx, and returns HTTP status plus the API body. This gives the agent substantial behavioral context for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well structured with clear labeled sections: Behavior, Parameters, Returns, and Use when. It front-loads the critical endpoint and write indication, and every section adds value without wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The definition is complete for a tool with no output schema: it explains what the response looks like, how errors and non-2xx statuses surface, and the operational constraints such as auth, rate limits, and retries. It also covers the main usage workflow and related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already documents both parameters thoroughly. The description adds useful semantics by clarifying that the entire JSON payload goes in the single body argument and is forwarded verbatim, including the important gotcha that the spec marks body optional but this endpoint expects one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Updates user information' alongside the endpoint 'PUT /v2/users/{id}', giving a specific verb, resource, and action. It differentiates from siblings by defining the behavior as replacing fields on an existing record and explicitly mentioning the create tool as the alternative when the record does not yet exist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly says to use this only when the user asked to change an existing record, and advises reading the record first to avoid overwriting unintended fields. It also names the create tool as the alternative for non-existing records, which is clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint, readOnlyHint, openWorldHint, and destructiveHint. The description adds substantial behavioral context: it replaces only the fields sent, is idempotent, has server-side auth injection, is throttled and retried on 429/5xx, and returns HTTP status plus JSON body with specific error mappings for 401/403/404/422. This goes far beyond the annotations and gives the agent a clear operational mental model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into labeled sections (Behavior, Parameters, Returns, Use when) and every sentence carries actionable information. The front-line declaration of WRITE/PUT and the concise update statement make the tool's purpose immediately clear. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with no output schema, the description covers everything an agent needs: auth requirements, rate limiting and retry behavior, response format, error semantics, idempotency, the body requirement, and when to route to the create tool instead. The absence of an output schema is compensated by the explicit 'Returns' section.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 a crucial nuance: the schema marks `body` optional, but the endpoint actually expects a body, and the whole payload should be forwarded verbatim into the single `body` argument. This is valuable practical guidance that prevents invocation failures.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Updates a user group'), states the HTTP method and path (PUT /v2/user_groups/{id}), and clarifies it modifies an existing record. This cleanly distinguishes it from sibling tools like create_user_group, deletes_user_group, and get_user_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly says to use this only when the user asked to change an existing record, tells the model to read the record first to avoid overwriting unintended fields, and says to use the create tool if the record does not exist. It also names related sibling tools, making the routing decision unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by explaining the write behavior, idempotency, server-side auth injection, throttling/retry behavior, and exact return/error semantics. This gives the agent a strong operational model of what happens when the tool is invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections, front-loaded purpose, and no filler. Each sentence earns its place: behavior, auth, retry, parameters, returns, errors, and usage guidance are all covered without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested body schema, role-dependent required fields, and absence of an output schema, the description supplies the missing operational context: return shape, error status meanings, idempotency, and the 'read first' overwrite warning. Together with the detailed input schema, an agent has everything needed to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is solid, but the description adds meaningful extra context: the entire payload must go in the single 'body' argument, is forwarded verbatim, and the endpoint expects a body even though the spec marks it optional. This compensates for a potential schema ambiguity without repeating every field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Updates the role assigned to the user.' It also distinguishes itself from related tools by explicitly framing this as changing an existing record and pointing to the create tool when the user does not exist yet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section explicitly says to call this only when changing an existing record, advises reading the current record first to avoid overwriting unintended fields, and directs to the create tool if the record does not exist. It also lists related user tools, making alternative selection clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by explaining that the operation creates a record or triggers an action, is not idempotent, has server-side auth, is throttled, retries on 429/5xx, and surfaces non-2xx responses as tool errors. This gives the agent a rich behavioral model without contradicting any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into clear labeled sections: purpose, behavior, parameters, returns, and usage. It is longer than average but every section contributes necessary operational detail; there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully covers the return format, error status meanings, auth requirements, rate limits, idempotency, and pre-call checks. It is complete enough for an agent to invoke the tool correctly and understand what happens afterward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already documents all parameters, the description adds crucial meaning: the entire JSON payload goes into the single `body` argument and is forwarded verbatim, and the `body` being optional in the spec does not mean the endpoint does not expect one. It also connects the optional seat-assignment behavior to the likely `add_to_active_seat` field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Add a user to the seat offering specified by the provided seat offering id.' It also mentions the optional seat-assignment behavior, distinguishing the operation from seat-offering creation, deletion, or removal. The HTTP verb and path add further precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section is explicit: only use when the user asked to create this, and the description instructs checking with a read tool that the target exists and the record is not already there. It also lists related seat-offering tools, providing clear context for choosing among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral context: permanent removal with no undo, server-side auth injection, throttling and retry behavior, and detailed success/error response semantics. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but each sentence earns its place: destructive warning, behavior, auth/throttling, parameter handling, return codes, and usage guidance. It is front-loaded with the most critical signal (destructive) and structured with clear labeled sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no output schema, the description fully covers what the agent needs: what the tool does, when to use it, what happens on success and failure, how authentication works, and how parameters are passed. No critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds important parameter guidance beyond the schema: the entire JSON payload goes in the body argument, body is optional per spec but expected by this endpoint, and id/uid are clearly tied to the seat offering and user. It also clarifies the remove_from_seat_offering boolean's effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove a user from a seat and optionally from the seat offering,' a specific verb-plus-resource statement that also matches the endpoint and title. It clearly distinguishes this deletion tool from related seat tools like add_user_seat_offering and update_seat_offering by naming them later.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states explicitly when to use the tool ('only after the user confirms the removal') and when not to ('To merely revoke access or deactivate, use the matching 🟡 update or unenroll tool instead'). It also lists related seat-offering tools, giving an agent clear routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description explains that the endpoint 'replaces the fields you send on an existing record in the live school,' that auth is 'injected server-side, never by the model,' and that calls are throttled and retried on 429/5xx. It also details the return format and maps common HTTP error statuses to causes. This adds substantial behavioral context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthier than average, but it is tightly structured with labeled sections: Behavior, Parameters, Returns, Use when. Each sentence carries operational value—auth, throttling, retries, error mapping, and tool selection—so the length is justified and every part is front-loaded for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description compensates fully by stating the return as 'HTTP <status> followed by the LearnWorlds JSON response body' and describing error conditions. It covers usage conditions, parameter nuances, authentication, rate limiting, retries, and related tools. An agent has everything needed to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds important operational nuance: the entire JSON payload goes in the single `body` argument, is forwarded verbatim, and although the spec marks `body` optional, this endpoint expects one. This prevents a likely misuse that the raw schema alone would not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '🟡 WRITE · updates data · PUT /v2/community/spaces/{id}' and states 'Updates the community space specified by the provided space id.' This is a specific verb+resource pairing. It also differentiates from sibling tools by explicitly saying 'use the create tool if it does not exist yet' and listing related Community tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is an explicit 'Use when: only when the user asked to change an existing record' statement. It provides concrete guidance to 'Read it first so you overwrite just the fields you mean to' and directs to the create tool when the record does not exist. This clearly routes an agent to the correct alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond annotations: it explains field replacement semantics, idempotency, server-side auth injection, throttling/retry behavior, response format, and error status mappings. This goes well beyond the readOnly/idempotent/destructive hints already provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: endpoint, behavior, parameters, returns, and when-to-use. Information is front-loaded with the write indicator and organized with labeled sections, making it easy for an agent to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter update tool with no output schema, the description covers everything needed: request construction, response shape, error surfacing, idempotency, rate limits, and routing to create for non-existent records. The rich inline body schema fills the remaining field-level detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema description coverage is 100%, the description adds critical parameter semantics: the entire JSON payload goes in the single `body` argument, it is forwarded verbatim, and although the spec marks `body` optional, this endpoint expects one. This prevents a real mis-invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Updates a seat offering' and clarifies the response is the updated resource. It also distinguishes itself from related seat tools by explicitly referencing create/delete/get siblings and stating it changes an existing record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Use when: only when the user asked to change an existing record.' It also gives an alternative, 'use the create tool if it does not exist yet,' and instructs the agent to read the record first to avoid overwriting unintended fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![Learnworlds-MCP MCP server](https://glama.ai/mcp/servers/ohneben/Learnworlds-MCP/badges/card.svg)](https://glama.ai/mcp/servers/ohneben/Learnworlds-MCP)

Score Badge

Copy to your README.md:

[![Learnworlds-MCP MCP server](https://glama.ai/mcp/servers/ohneben/Learnworlds-MCP/badges/score.svg)](https://glama.ai/mcp/servers/ohneben/Learnworlds-MCP)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ohneben/Learnworlds-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server