Cubite LMS: Learning Management System

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

Annotations already declare readOnly/destructive=false, and the description layers on non-obvious domain behavior: an applicant is not enrolled until approved, one application per learner per course, and a rejected learner reapplying reopens the same application as pending with new answers. That lifecycle detail materially affects how an agent interprets 'pending' rows.

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

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

Front-loaded with purpose, then routing, then data shape; every clause carries information. It is dense and runs long with stacked semicolons, and the full return-object enumeration is heavy, though defensible since no output schema exists.

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

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

With no output schema, the description supplies the return envelope ({total, count, applications:[...]}) and field list, plus the applicationData shape variants. Nothing an agent needs to call or interpret this list tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds semantics the schema lacks, framing status:'pending' as the review queue and courseId as scoping to one course's queue. Limit/offset paging semantics are left entirely to the schema, so it stops short of a 5.

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

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

States a specific verb and resource ('List applications to courses that require applying before enrollment'), plus ordering ('newest first') and payload scope ('each with the applicant and their answers'). It explicitly contrasts itself with the sibling enrollment_list, so an agent can pick between them without opening either schema.

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

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

Gives explicit routing: use enrollment_list for enrolled or waitlisted learners, status:'pending' is the review queue, add courseId for a single course's queue, and application_review handles decisions by id. Both when-to-use and when-to-use-something-else are stated.

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

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

Annotations only flag a destructive, non-read-only write; the description goes well beyond them by disclosing the concrete side effects (immediate enrollment, prerequisites skipped, access period applied, emails sent), the idempotency semantics, and the non-reversal of a rejection. These are the high-value operational facts an agent must know before invoking a destructive tool.

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

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

Four dense sentences, front-loaded with the action and its irreversible consequence, then sibling routing, then the return shape. Nothing is padding; each clause carries a distinct fact.

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

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

Despite there being no output schema, the description states the return shape {id, status, decisionNote, reviewedAt} and covers the edge cases (repeat decisions, rejection-after-approval, unsolicited enrollment). Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by tying each enum value to a downstream consequence (approved enrolls and emails a link; rejected records and emails the note) and explicitly notes decisionNote appears in the rejection email only. That linkage is richer than the per-field schema text.

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

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

The description names a specific verb pair (approve/reject) and a precise resource (one course application from application_list), and it explicitly delineates itself from enrollment_revoke and enrollment_create. An agent can distinguish this from every sibling without opening a schema.

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

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

It gives explicit routing: use enrollment_revoke to remove an existing enrollment, and enrollment_create to enroll someone who never applied. It also states the idempotency behavior (repeating a decision does nothing; rejecting an already-approved application does not unenroll), which is exactly the when/when-not guidance an agent needs.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false; the description reinforces this ('static reference data and reads nothing from your site') and adds behavioral context beyond the annotations: the tier taxonomy, section eligibility rules, and the unknownTypes error behavior. It stops short of describing pagination or response size limits beyond 'one large response.'

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

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

Dense but front-loaded: the core purpose and read-only nature come first, then the call pattern, then tier/section reference. Every sentence carries information, though the section rules compress several distinct caveats into a long sentence.

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

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

With no output schema, the description carries the return-shape burden and does so well, explaining both the compact index and the expanded `types` response (data shape, enums, example) plus error handling. 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.

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

Schema coverage is 100%, so a baseline of 3 is warranted, but the description adds semantic meaning the schema lacks: what 'compact index' returns per row (type, tier, when to use it), what tier labels mean (prose/section/visual/media), and the section semantics/caveats (courseAssessments is course-only; notForBlogContent despite its name lists types never to emit).

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

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

States a specific verb and resource ('Return the EditorJS block catalog') and immediately clarifies scope: 'the block types you can write as `blocks` and the exact `data` shape of each.' This distinguishes it clearly from siblings like course_content_set, which it references as the consumer.

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

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

Gives an explicit two-call workflow ('no arguments for a compact index... then again with `types` set to only the blocks you will emit') and an explicit exclusion: prose content needs no catalog because markdown is auto-converted. The routing condition for the tool is unambiguous.

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

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

Annotations declare a read-only, non-destructive operation, and the description adds substantial behavior beyond that: version 0 with no blocks means nothing written, nonexistent versions are not-found errors, older revisions include savedAt, and writing is additive rather than history-erasing. This is rich context an agent cannot get from annotations.

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

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

Front-loaded with the core purpose, then scoping, return shape, and workflow in a dense multi-sentence block. Every sentence carries information, though the rollback sentence and sibling routing make it longer than strictly minimal.

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

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

With no output schema, the description compensates by naming the return shape ({courseId, version, blocks} plus savedAt) and edge-case semantics. Nothing needed to call or interpret the result is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: what `version` selects (a saved revision from course_version_list), its valid range, and the effect of omitting it. Slightly exceeds the schema's own wording.

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

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

States a specific verb+resource and the exact representation returned (EditorJS blocks), plus the H2/H3 structural convention. It also distinguishes itself from siblings course_get and fetch by naming what those return instead.

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

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

Explicitly routes: use course_version_list to find revisions, course_get for settings, fetch for catalog summary, and read the current version before course_content_set to preserve block ids. It also covers the rollback workflow. When/when-not guidance is fully present.

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

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

The description adds substantial behavioral context beyond the destructiveHint=true annotation: learners see changes immediately, every call creates a version, earlier versions remain readable for rollback, and block ids are essential for preserving learner history. It also discloses the return value (new version number and block count) despite no output schema, which is unusually thorough.

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

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

The description is dense but well-structured, front-loading the core action and then covering usage, format, ids, and versioning in a logical order. Every sentence carries actionable information, with no filler.

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

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

Given the complexity of a destructive replace operation with no output schema, the description covers everything an agent needs: scope, alternatives, format requirements, id handling, rollback path, and return values. It is complete and leaves no critical gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining the semantics of `blocks` versus `markdown` (EditorJS vs prose only, markdown cannot express graded blocks), the heading conventions (H2 for sections, H3 for units), the importance of block ids, and that blocks wins over markdown if both are sent. This meaningfully enriches the schema's own descriptions.

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

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

The description states a specific verb and scope: 'Replace a course's lessons by saving a complete new content version.' It distinguishes itself from siblings by naming course_update for settings and course_content_get for reading earlier versions, so the agent knows exactly what this tool does and doesn't do.

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

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

It gives explicit when-to-use guidance by contrasting this tool with course_update ('settings such as price or visibility are changed with course_update instead') and clarifies that it is not a patch ('send the whole course every time'). It also points to course_content_get for rollback, naming alternatives directly.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description still adds real value beyond them: no emails or webhooks fire, a rejected call creates nothing but names need not be unique so each success adds another course, and the reading-time gate starts on.

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

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

Front-loaded and dense with no filler sentences; each clause carries routing or behavior information. It is a wall of text for a 27-parameter tool, but nearly every sentence earns its place.

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

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

Complete for a large create tool: it covers side effects, defaults with workflow consequences, error/failure behavior, the return shape (name, id, slug) despite no output schema, and the next step. Little an agent needs before calling it is missing.

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

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

Schema description coverage is 100%, so the 27 properties are already fully documented and the baseline is 3. The description adds some scope knowledge not derivable from the schema (prerequisites, application questions and certificateConfig are deliberately absent here), but the field-level semantics themselves duplicate what the schema already states.

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

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

Opens with a precise verb+resource and immediately scopes it: 'Create a new course on this site: settings only, no lessons yet.' It explicitly distinguishes itself from the sibling course_duplicate, so an agent can pick between them without opening schemas.

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

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

Gives explicit when/when-not routing ('to copy an existing course with its lessons, use course_duplicate'), a build-then-publish workflow (create with isVisibleInCatalog:false, publish later with course_update), and directs follow-on work to course_update and course_content_set.

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

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

Annotations already declare destructiveHint=true, but the description goes far beyond: it enumerates exactly what is destroyed (content versions, enrollments, progress, certificates, discussions, payment records and their effect on revenue reports, applications, learning-path steps, group links), states irreversibility, and describes the detach-vs-delete branch. This is precisely the behavioral context an agent needs before 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.

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

Dense but front-loaded: the detach/delete distinction comes first, then destruction list, then the refusal+force condition, then the alternative and the pre-check. Every clause carries actionable information and nothing is redundant.

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

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

With no output schema, the description correctly supplies the return value ('whether the course was deleted or detached'). Combined with the destruction list, force semantics, and the alternative route, nothing needed to call this safely is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it frames force as the override for the enrolled-learners refusal and implies id identifies the course. It stops short of documenting types/defaults beyond what the schema already carries.

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

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

States a specific verb+resource (delete a course) and immediately distinguishes the two possible semantics — detach from this site vs. permanent deletion. An agent can tell this apart from siblings like course_update or enrollment_revoke without opening any schema.

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

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

Explicitly names alternatives and conditions: use course_update with isVisibleInCatalog:false to hide instead of delete, and use enrollment_list(courseId) before forcing. It also states the exact precondition (enrolled non-waitlisted learners) under which the call is refused.

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

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

Annotations already disclose that this is a non-read-only, non-destructive operation, but the description adds extensive behavioral detail: what is copied (settings, lessons as version 1, SCORM/xAPI, discussions, tags, certificate template, instructors), what is not copied (enrollments, slug, certificate numbering), timeout and rollback behavior, and the fact that a failed copy is rolled back.

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

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

The description is long but well-structured and front-loaded: it begins with the core purpose and alternative, then details copy behavior, exclusions, warnings, and return value. Most sentences carry useful, non-redundant information, though the density is high enough to be a slight readability tax.

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

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

With no output schema, the description states the return value ('Returns the new course object') and covers side effects, exclusions, prerequisites, and failure behavior. It gives an agent everything needed to invoke the tool responsibly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining authorId's default, its side effect of adding the user to instructors, and its role as author of version 1. The id parameter is already well described in the schema.

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

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

States a specific verb and resource ('Duplicate course') and explicitly distinguishes itself from course_create for a blank course. An agent can identify the operation and its scope without opening the schema.

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

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

Provides clear when-to-use guidance ('fastest way to start a new cohort or a variant of a template'), names the alternative (course_create), and adds operational prerequisites such as setting a slug via course_update and checking course_list before retrying a timeout.

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

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

Beyond the read-only annotation, the description discloses that includeConfig requires courses:write and that a read-only connection gets an error rather than silently missing fields. It also describes return shapes and not-found behavior, which are valuable behavioral details.

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

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

The description is dense but front-loaded with the core purpose, then alternatives and return behavior. Every sentence adds useful routing or behavioral information without waste.

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

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

With no output schema, the description explains both possible return forms, including the includeConfig variant, and the not-found error case. It is complete enough for an agent to call the tool correctly.

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

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

Schema coverage is 100%, so both parameters are already documented clearly in the schema. The description reinforces includeConfig's effect and adds the read-only error behavior, but most parameter meaning is already present in the schema, making 3 the appropriate baseline.

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

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

The description states a specific verb and resource: retrieving one course's settings record by id, and explicitly says it returns the same course object as course_list with named fields. It also distinguishes this from course_content_get for lessons and fetch for a citable summary.

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

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

It gives explicit routing: use course_content_get for lessons and fetch for a plain-text summary with public URL. It also states when and why to pass includeConfig, including the permission requirement and read-only connection error.

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

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

Annotations already declare a read-only, non-destructive operation; the description adds ordering, hidden-course inclusion, exact returned fields, enrollment counting semantics, and paging behavior. 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.

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

The scope is front-loaded, followed by alternatives, return shape, and paging. Despite being dense, every sentence carries decision-relevant information and there is no filler.

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

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

With no output schema, the description fully explains the returned array and key fields. It also covers scope, exclusions, alternatives, and paging, leaving no major ambiguity for calling the tool correctly.

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

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

Schema coverage is 100%, so `limit` and `offset` are already documented. The description still adds useful paging semantics by explaining how to advance `offset` and when to stop.

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

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

States a specific verb and resource: list every course on the site, with scope clarified as full inventory including hidden and slugless courses. It also distinguishes itself from `search` and `course_get`, so an agent can select it without opening another schema.

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

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

Explicitly says it has no keyword filter and returns no page URLs, then names `search` for keyword/public-URL lookup and `course_get` for one course record. Paging guidance is also given.

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

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

Goes well beyond the destructiveHint=true annotation: it states scalar fields patch while null clears nullable ones, lists are replaced whole, an invalid value rejects the call and leaves the course unchanged (atomicity), saves land in the change log, and no emails or webhooks fire. It also warns that certificateConfig replaces the stored object so omitted keys are deleted, which is exactly the kind of destructive nuance an agent needs.

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

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

Front-loaded with purpose, then semantics, then constraints, with zero filler sentences; each clause carries distinct information. It is a single dense run-on paragraph, though, which makes the individual rules harder to scan than a short bulleted structure would.

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

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

For a 31-parameter, deeply nested mutation tool this covers the essentials: patch semantics, replacement semantics, atomic failure behavior, side effects, change-log behavior, and the return shape ('same shape as course_get'). With no output schema, it still tells the agent what comes back and what the shared mutable prerequisites are.

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

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

Schema description coverage is 100%, so the 31 parameters are already documented and this is the baseline-3 case. The description restates the patch-vs-replace rule and the accessDurationDays-to-new-enrollments caveat, but those points are also present in the schema, so it adds little parameter meaning beyond the structured fields.

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

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

Names a specific verb+resource (update a course's settings) and enumerates the field families covered, from catalog text and pricing to instructors, prerequisites, application form and certificateConfig. It also carves out what this tool is NOT (lessons belong to course_content_set), so an agent can separate it from siblings like course_content_set and enrollment_update.

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

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

Explicitly routes two adjacent tasks to the correct siblings ('replace them with course_content_set', 'change existing learners' expiry with enrollment_update') and points to course_get with includeConfig:true as the way to read current list values before replacing them. There is no explicit statement of when this tool should be chosen over course_create, but the update/create distinction is self-evident.

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

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

Annotations already declare readOnly/not-destructive, and the description adds substantial behavior: authorName appears only with members:read, versions are never pruned, every save adds one, the first row is the current version, and paging works by raising offset in limit-sized steps. It also discloses the return shape, going beyond the safety profile the annotations carry.

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

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

Dense but front-loaded with the core purpose, and nearly every clause carries actionable detail (return fields, ordering, paging, restoration). Some sentences are long and packed, slightly straining readability but without wasted content.

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

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

With no output schema, the description compensates by stating the return object ({courseId, total, count, versions}) and the per-row fields, plus ordering and pagination semantics. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning by explaining that limit:1 yields the current version number and save time, and that offset should be raised in steps of limit to page backward.

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

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

States a specific verb+resource: lists a course's saved content versions, newest first, metadata only. It enumerates the returned fields and name-checks the sibling (course_content_get) used to read blocks, so an agent can distinguish it from related tools.

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

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

Explicitly routes usage: use it to find an earlier version to inspect or restore, then call course_content_get(version:N); and it states when NOT to use it ('to read the current lessons you do not need it'). Restoration path via course_content_set is also named.

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

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

Despite annotations already flagging destructiveHint=true, the description adds rich behavior beyond them: per-learner partial-failure semantics, that an unexpected server error aborts the batch with no per-learner results but prior enrollments persist, that already-enrolled learners keep enrollment with created:false while invites are re-sent and sign-in links replaced, and that a full-failure batch errors. This is substantial disclosure well beyond the structured fields.

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

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

It is a single dense paragraph but well front-loaded: purpose first, then the sibling alternative, then failure/retry behavior, then return shape. Every clause carries operational meaning, though the length pushes the limit of tightness.

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

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

With no output schema, the description fully explains the return value ('Enrolled N, failed M' plus per-learner fields and the all-failed error case), and it covers idempotency, retry safety, and prerequisite behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning not in the schema: that sendInvite suppresses email unless true, that it overrides issueMagicLink, and that emails/learners follow the same account-creation and prerequisite rules as enrollment_create. This is genuine added value on top of a fully documented schema.

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

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

The description states a specific verb+resource+scope ('Enroll up to 100 learners in one course in a single call') and explicitly contrasts itself with the sibling enrollment_create, naming the exact conditions that select the other tool (one learner, redirectTo, externalReference). An agent can differentiate it from enrollment_create without opening any schema.

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

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

It gives explicit when-to-use-this vs when-to-use-the-alternative guidance: 'use enrollment_create for one learner or to pass redirectTo or externalReference.' It also notes the cap of 100 and the course-id source (course_list), leaving nothing to inference.

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

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

Goes well beyond the annotations: it discloses that an account is still created even if the user declines, that prerequisites are enforced unless skipPrerequisiteCheck:true, the exact default email behavior (nothing sent unless sendInvite:true), that magic links are single-use/24h and minting cancels earlier links, the duplicate-enrollment side effect (no new record, created:false, but status label reset to "completed"), and the enrollment.created webhook. This is unusually rich side-effect disclosure for a destructive write tool.

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

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

Front-loaded with the core action and zero filler sentences, but it is one dense run-on paragraph where semicolon-joined clauses blend usage guidance, side effects, and return values. It would read better split into use-when / behavior / returns groupings, though nothing is wasted.

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

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

With no output schema, the description compensates by enumerating the return shape ({enrollment, user, magicLinkUrl, created, emailSent, externalReference}) and explaining key values like created:false and emailSent. Combined with the side-effect coverage, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter behavior not in the schema: sendInvite overrides issueMagicLink, the magic link is what you use for your own welcome email, and no payment is recorded so checkout still shows. These interactions meaningfully extend the per-field descriptions.

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

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

The first clause states a specific verb+resource (enroll one learner in a course by email) and immediately scopes it against siblings: enrollment_bulk_create for many learners, application_review for approvals. An agent can distinguish this from enrollment_update and enrollment_bulk_create without opening any schema.

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

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

Explicit alternatives are named with the condition that selects each: bulk create for many learners, application_review to approve an applicant, enrollment_update to change an existing enrollment. It also states what is NOT validated (price, application requirement, enrollment dates) and where to get course ids (course_list).

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

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

Annotations already cover the read-only safety profile, and the description adds substantial behavior beyond that: default sort order, the empty-list outcome for an unknown email, the pagination contract ({total, enrollments}, page with offset until total), the row field list, and the non-obvious semantics of the "pending" status label relative to waitlist unlocking.

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

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

Purpose and default ordering are front-loaded, and nearly every clause carries information. The middle section is a dense single paragraph of semicolon-chained filter cases, which is harder to scan than a short list would be, but nothing is truly wasteful.

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

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

There is no output schema, so the description carries that burden and does so: it enumerates row fields, states the envelope shape and pagination method, and warns that an unmatched email returns an empty list rather than an error. Nothing needed to call this tool correctly appears to be missing.

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

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

Schema coverage is 100%, so the per-parameter baseline is 3; the description goes further by explaining cross-parameter behavior the schema cannot (email/userId + courseId yields the learner's single enrollment, status:"pending" with waitlisted:false isolates unlocked learners) and that status means the enrollment, not course completion.

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

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

States a specific verb and resource ("List enrollment records on this site"), names the default ordering (newest first), and characterizes the rows (who is enrolled or waitlisted in which course, and progress). It is immediately distinguishable from the sibling mutators enrollment_create/update/revoke and from application_list.

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

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

Explicitly routes the agent: applications awaiting decision are not enrollments and should use application_list, and single-learner changes belong to enrollment_update or enrollment_revoke. It also spells out the when-to-use condition for each filter combination (email/userId with or without courseId, waitlisted true/false, status:"pending" + waitlisted:false).

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

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

Annotations only give destructiveHint=true; the description goes well beyond by disclosing exactly what is destroyed (the enrollment record, the waitlist place) and what is preserved (progress, graded work, issued certificates, the account and site membership). It also states the side-effect profile: no email is sent, and the exact return text.

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

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

Front-loaded with the action and its consequences before the routing alternatives and identifier guidance. It is one dense paragraph rather than scannable fragments, but nearly every clause carries distinct information.

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

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

With no output schema, the description still supplies the return value ('Enrollment revoked.'), the error case, and the full side-effect envelope. Nothing an agent needs to call this mutation safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds sourcing context the schema lacks: identify the learner by email or userId 'as shown in enrollment_list rows' and get course ids from course_list. It does not restate the userId-wins precedence beyond what the schema already covers.

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

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

States a specific verb and resource (revoke one learner's enrollment in a course) and immediately distinguishes itself from the two nearest siblings: enrollment_update for changing expiry/waitlist/status and enrollment_create for re-enrolling. An agent can route correctly without opening a schema.

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

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

Explicitly names alternatives and the conditions selecting them ('to change an expiry, waitlist place or status label instead, use enrollment_update'; re-enrolling later with enrollment_create). It also states the not-found condition for a learner who is not enrolled, and points to enrollment_list and course_list for obtaining identifiers.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds context the annotations cannot: mutations are in place and preserve learner progress, omitted fields stay unchanged, a non-enrolled learner yields a not-found error, and no email is sent. It also discloses the return payload shape, which is significant given there is no output schema.

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

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

Front-loaded with the core purpose, then alternatives, then semantics, with no filler sentences. It is dense and long for a single tool, but each clause (waitlist mechanics, no-email behavior, return shape) carries information an agent needs, so the length is largely earned.

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

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

No output schema exists, so the description compensates by listing the returned enrollment fields (courseId, userId, status, isWaitListed, enrolledAt, expiresAt, user). Combined with annotation-covered safety and explicit error behavior, nothing needed to invoke this mutation correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains that identity is email or userId, that omitted fields are unchanged, and the non-obvious interaction of isWaitListed:false with status:"completed" to surface Start/Continue. It stops short of documenting any edge semantics the schema already owns.

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

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

States a specific verb and resource ('Change one existing enrollment in place') and enumerates the three mutable aspects: access expiry, waitlist membership, and status label. It directly distinguishes itself from enrollment_create and enrollment_revoke by naming both siblings, so an agent can select it without opening any schema.

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

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

Explicit routing: 'Use it for every change to an enrollment that exists; to add one use enrollment_create, to remove one enrollment_revoke.' It also names the waitlist-promotion idiom (isWaitListed:false with status:"completed") and the prerequisite that the learner must be enrolled, covering when-not (not-found error) and alternatives.

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

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

Annotations cover the safety profile (readOnly, non-destructive, non-open-world), and the description adds behavior the annotations cannot: the exact return shape, the error-collapsing rule (missing doc, foreign site, unreadable type all yield the same not-found), the invalid-id rejection, and that a course's text is the catalog summary rather than its lessons.

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

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

Front-loaded with purpose then progressively adding format, return, error, and alternative guidance — each sentence carries information. Slight redundancy in restating the return shape `{id, title, text, url, metadata}` when an output schema already exists.

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

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

Covers purpose, parameter format, return content, error semantics, and sibling routing. With an output schema present, no further explanation of return values is required, so nothing material is missing.

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

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

Schema coverage is 100%, so the schema already documents `id`. The description still adds real value: it must be passed exactly as search returned it, needs the type prefix, and a prefix-less id is rejected as invalid — format constraints beyond the schema text.

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

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

States a specific verb (read one result) plus resource (a result previously found via `search`) and names the pair relationship with `search`. It also distinguishes itself from the course-oriented siblings by framing output as plain text with a public page URL for quoting/citing.

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

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

Explicitly gives the when ('for quoting or citing it in an answer') and the when-not with named alternatives: 'To work with a course rather than quote it, use course_get ... and course_content_get for its lessons.' The agent has a clear routing rule.

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

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

The description adds substantial behavior beyond the read-only annotations: matching is a case-insensitive phrase against course names and descriptions, results are ordered by name, courses without slugs are omitted, catalog-hidden courses are included, and at most 10 results are returned. It also discloses the exact return shape and next-step handoff to `fetch`.

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

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

The description is dense but well structured, leading with purpose and then layering pairing, matching rules, result behavior, and sibling alternatives. Every sentence contributes actionable information for an agent.

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

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

Given the simple one-parameter schema, available output schema, and read-only annotations, the description covers everything needed: purpose, matching rules, result limits, edge cases, return shape, and next steps. No critical calling context is missing.

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

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

Schema coverage is 100%, so the schema already documents the `query` parameter. The description still adds useful matching semantics and practical guidance about using one or two distinctive words, though it does not add new formal parameter constraints.

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

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

The description states a specific verb and resource: it searches this Cubite site's courses by keyword and returns public page URLs. It also explicitly distinguishes itself from the sibling `course_list` tool, which is for listing rather than keyword search.

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

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

It explains exactly when to use this tool: for linking to or citing courses, as the search half of the search/fetch pair, and advises using one or two distinctive words. It also names the alternative `course_list` for inventory-style listing and `fetch` for retrieving citable text from a result.

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