Cubite LMS: Learning Management System

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

Annotations cover the safety profile (readOnlyHint, openWorldHint=false), and the description adds substantial domain behavior: one application per learner per course, reapplication reopens the same record as pending, applicant not enrolled until approved, and the applicationData shape including legacy flat objects. This is context far beyond what the 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.

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

Dense and front-loaded with the core purpose and the routing alternative first, then semantics, then return shape. It is long, but nearly every clause carries actionable information (reapplication semantics, output fields) that has no other home since there is no output schema.

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:[...]}), the nested applicationData variants, and the review/decision fields, plus enum semantics for status. Nothing an agent needs to call or interpret this tool correctly appears 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 beyond the schema by framing status:"pending" as the review queue and courseId as selecting a single course's queue. It does not add format/syntax details for limit/offset beyond 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?

States a specific verb and resource (list applications to courses requiring approval) with qualifying scope (newest first, includes applicant and answers). It explicitly names the sibling enrollment_list as the alternative for enrolled/waitlisted learners, so an agent can distinguish it without opening a schema.

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

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

Gives explicit when-to-use guidance: status:"pending" is the review queue, add courseId for a single course's queue, and use enrollment_list otherwise. It also tells the agent the follow-up action (approve/reject via application_review with the id).

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

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

With annotations only providing readOnlyHint=false and openWorldHint=false, the description carries rich behavioral detail: approval instantly enrolls with prerequisites skipped and the access period applied, both branches send emails, and decisions are idempotent. This is exactly the side-effect disclosure a mutation tool 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-loads the core action, then layers consequences, idempotency, and alternatives. The semicolon structure keeps it dense but every clause carries actionable information; 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?

Covers the decision semantics, side effects, idempotency, non-reversal behavior, sibling routing, and even the return shape. An agent has everything needed to call this correctly without opening another tool.

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

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

Schema description coverage is 100%, so all three parameters (id, decision enum, decisionNote) are already documented in the schema, including the note appearing only in the rejection email. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

Names a specific verb pair (approve/reject) and the exact resource (one course application), and scopes it to an item from application_list. An agent can immediately distinguish this from enrollment_create and enrollment_revoke.

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 alternatives and the conditions that select them: enrollment_revoke for removing an existing enrollment, enrollment_create for someone who never applied. It also states the when-does-nothing cases (repeat decisions, rejecting an already-approved application).

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 readOnlyHint/openWorldHint, it discloses that the data is static and reads nothing from the site, that `courseAssessments` blocks are valid ONLY in course content, and that `notForBlogContent` is a misleading name for 'never emit anywhere'. Those are non-obvious behavioral traps an agent could otherwise fall into.

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 the calling pattern, then tier/section semantics. Dense and largely waste-free, though the middle section is a long run of clauses that could be trimmed slightly for scannability.

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 burden of describing returns and does so: one line per type for the compact index, full catalog when expanded, and unknown-name handling is covered by the schema. 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 names and interactions are already documented. The description still adds meaning the schema lacks: what the tier labels (prose/section/visual/media) imply and why you would prefer `types` over `detail: 'full'`. That is incremental value above the baseline 3 for full-coverage schemas.

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: the block types you can write as `blocks` and the exact `data` shape of each.' An agent can immediately tell this apart from siblings like course_content_set or course_content_get, and the static-reference nature is declared up front.

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-step workflow ('call with no arguments for a compact index ... then again with `types` set to only the blocks you will emit') and an explicit when-not ('Prose needs no catalog: `markdown` ... is converted to blocks for you'). It also routes section selection with a caveat for `courses`.

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 declare readOnlyHint and openWorldHint, but the description adds real behavioral detail: the return shape {courseId, version, blocks}, savedAt for older revisions, that version 0 with no blocks means nothing has been written, that a nonexistent version is a not-found error, and that content_set saves a new version rather than erasing history.

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 core action is front-loaded and every subsequent clause (sibling routing, return shape, error cases, set/rollback workflow) carries distinct information with no filler. It is dense and runs long as a single block, which slightly hurts scannability, but 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?

There is no output schema, so the description carries the return-value burden and does so fully by naming the returned fields and the savedAt variant. Combined with error semantics and version handling, an agent has everything needed to call and interpret this reliably.

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, and the description adds semantic value beyond the schema: `version` selects an older saved revision, must come from course_version_list, and omitting it yields the current version, with explicit error behavior for a missing version. The `id` parameter gets no additional meaning, keeping it 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 ('Get a course's lessons as EditorJS blocks') and immediately clarifies the domain structure (H2 headers are sections, H3 are units). It explicitly contrasts itself against siblings course_get and fetch, so an agent can select correctly 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?

Gives explicit when-to-use routing: use this for authoring source, course_version_list to list revisions, course_get for settings, fetch for catalog summary. It also states a concrete workflow prerequisite — read the current version before course_content_set to preserve block ids — and describes the rollback procedure.

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?

Annotations declare readOnlyHint=true, but the description goes well beyond that: it discloses that includeConfig requires courses:write and that a read-only connection gets an error rather than silently missing fields — a non-obvious failure mode. It also documents the return shape (course object vs {course, config}) and that a course not on the site is a not-found error, none of which the 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.

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

Front-loads the core verb and resource, then layers the includeConfig branch, sibling routing, return shape, and error mode in dense, non-redundant sentences. Every clause earns its place; 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?

Covers purpose, conditional parameter behavior, permissions, failure modes, return shape, and sibling alternatives. With no output schema, the description compensates by describing exact return shapes, making it complete for an agent to call 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 schema already documents both id and includeConfig in detail, including field lists and permission requirements. The description repeats the includeConfig semantics without adding format or syntax beyond the schema; baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Get one course's settings record by id') and pins down exactly which representation is returned by equating it with the course_list object's fields. It also distinguishes itself from course_content_get and fetch by naming both siblings and their distinct purposes.

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: use course_content_get for lessons, use fetch for a citable plain-text summary with public URL. It also states when to add includeConfig and what permission that branch requires, so the agent knows the conditional path.

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, so the safety profile is covered. The description adds genuinely useful non-annotation behavior: hidden courses are included, no page URLs are returned, and it spells out the paging mechanic (raise offset by limit until a page holds fewer than limit). Minor gap: no explicit note on auth or rate limits.

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

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

Front-loaded with the core scope and the sibling routing, with the return envelope and paging instructions following. It is dense and packs a lot into a few sentences, though the long return-field list is the least essential clause.

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

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

No output schema exists, and the description compensates by enumerating the returned fields (id, name, slug, catalog flags, subjects, enrollmentCount semantics) plus pagination strategy. 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 the baseline is 3. The description goes beyond the schema by giving a concrete paging algorithm tying limit and offset together, which adds operational meaning neither parameter documents alone.

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

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

States a specific verb and resource (list every course on the site) and pins the scope as the full inventory including hidden courses and slug-less records. It explicitly distinguishes itself from `search` and `course_get`, so an agent can route 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 the alternatives and the condition that selects each: use `search` for keyword lookups plus public page URLs, `course_get` for a single course's record. It also states the negative case (no keyword filter) that would otherwise tempt a wrong call.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, yet the description adds atomicity (an invalid value rejects the call and leaves the course unchanged), side-effect scope (recorded in the change log, emails no one, fires no webhook), and patch semantics (scalar fields patch, null clears, lists replace whole). This is far beyond what the annotations convey.

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: purpose first, then patch semantics, then side effects, then sibling routing. Every clause carries information, though the long semicolon-chained sentence around certificateConfig is heavier than ideal for scanning.

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 mutation with nested objects and no output schema, the description covers return shape (same shape as course_get), mutation semantics, error behavior, and redirection to the correct siblings. Nothing an agent needs to invoke it 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 cross-parameter meaning the schema cannot: scalars patch while lists are replaced wholesale, and certificateConfig is a single object whose omitted keys are deleted. It also flags that accessDurationDays affects only new enrollments, which no per-field schema text frames.

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 (update) and resource (course settings) and enumerates the field groups covered, from catalog text to certificateConfig. An agent can distinguish it from course_create, course_delete and course_content_set 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 routes to alternatives: lessons go to course_content_set, existing learners' expiry goes to enrollment_update, and current list values come from course_get with includeConfig:true. It states when the tool is the wrong choice, not just when it fits.

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 declare readOnlyHint/openWorldHint, but the description adds substantial behavior: newest-first ordering, first row is the current version, versions accumulate and are never pruned, authorName appears only with members:read, the exact return shape, and that restoring adds a new version rather than overwriting history.

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-loads the purpose before any procedural detail, and each following sentence adds a distinct actionable fact. Nothing 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?

Although there is no output schema, the description spells out the returned object shape ({courseId, total, count, versions}) and the per-row fields, and it explains the read-only, accumulating nature of the version history. 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 defaults and caps are already documented. The description nevertheless adds operational meaning beyond the schema: paging back by raising offset in steps of limit, and using limit:1 to read the current version's number and save time.

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, ordering and scope: 'List a course's saved content versions, newest first, as metadata only', then enumerates exactly which fields come back. It clearly distinguishes itself from course_content_get, which returns blocks rather than version indices.

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 the situation to use it (find an earlier version to inspect or restore) and the situation not to (reading current lessons, which course_content_get returns by default), and routes to the correct sibling for each follow-up action. Also covers pagination and restore procedures.

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 declare readOnlyHint=false and openWorldHint=false, so the description carries the real behavioral burden and does so well: partial-success semantics, per-learner failure isolation, server-error behavior with no per-learner results, idempotent re-runs, invite re-sending and sign-in link replacement. It does not explicitly restate the safety profile (non-destructive, no auth prerequisites), but the failure/re-run semantics are unusually thorough. No contradiction with readOnlyHint=false.

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 and sibling routing before the behavioral caveats, and every sentence carries substantive information rather than filler. It is dense, with long multi-clause parentheticals, which costs a point on readability but not on 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?

No output schema exists, yet the description fully describes the return shape ('Enrolled N, failed M' plus per-learner email, ok, created, emailSent, magicLinkUrl, enrollment / error, missingPrerequisites) and the all-fail error case. Combined with the mutation caveats, 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 schema already documents each parameter including defaults. The description adds useful cross-parameter context — sendInvite:true gating email, learners-vs-emails precedence, and the course_list pointer for courseId — plus the redirectTo/externalReference note that lives only in the description, so it exceeds the baseline 3.

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

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

States a specific verb and resource with explicit scope ('Enroll up to 100 learners in one course in a single call') and directly differentiates from the sibling enrollment_create ('use enrollment_create for one learner or to pass redirectTo or externalReference'). An agent can route between the two 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 when-to-use and when-not-to-use guidance: this tool for bulk, enrollment_create for a single learner or when redirectTo/externalReference are needed. It also states the shared rule set inherited from enrollment_create, so prerequisites and invite behavior are 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 only cover readOnlyHint=false and openWorldHint=false, and the description carries the rest exceptionally well: no price/application/date checks, prerequisite gating with the skipPrerequisiteCheck escape, passwordless account creation even on refusal, no Cubite email unless sendInvite:true, single-use magic link semantics, the fired enrollment.created webhook, and the idempotent re-enroll behavior (created:false, expiry preserved, status label reset).

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 routing, but it is a dense run-on that mixes routing, side effects, edge cases and return shape into few sentences. Every clause is substantive, yet the volume pushes past what an agent needs in one read.

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

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

With no output schema and eight parameters on a mutation tool with side effects, the description enumerates the returned keys ({enrollment, user, magicLinkUrl, created, emailSent, externalReference}) and closes the loop on the constant-default course id source. Nothing material for a correct call 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% and the schema itself is unusually rich, so the baseline is 3. The description largely restates the same parameter facts (skipPrerequisiteCheck, sendInvite default, magicLinkUrl issuance) rather than adding syntax or constraints the schema lacks.

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

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

Specific verb+resource ('Enroll one learner in a course by email') with an explicit account-lookup-or-create scope. It names the siblings it is not (enrollment_bulk_create for many, application_review for approvals, enrollment_update for changes), so an agent can route 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?

Explicit when-to-use and when-to-use-something-else: bulk for many learners, application_review for approving applicants, enrollment_update for changing an existing enrollment, course_list for ids. It even carves out the already-enrolled case and explains what happens instead.

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

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

With readOnlyHint=true and openWorldHint=false already covering the safety profile, the description adds substantial non-obvious behavior: newest-first ordering, an unknown email returning an empty list rather than an error, the counterintuitive status:"pending" + waitlisted:false case (learners unlocked from the waitlist who still see an enrollment step), and offset-until-total pagination. This is exactly the extra context annotations cannot 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?

Purpose and the alternative-tool pointer are front-loaded, and there is no filler. However, the body is a single dense semicolon-chained paragraph and repeats some status detail already documented in the schema, which slightly hurts scanability for a 7-parameter tool.

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?

Although there is no output schema, the description fully specifies the return contract — {total, enrollments} plus every row field (courseId, userId, status, isWaitListed, enrolledAt, expiresAt, user object, progressPercentage, completedAt) — and explains how to page with offset. An agent has everything needed to call and consume the result.

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 goes beyond the per-field schema by explaining cross-parameter semantics the schema states only in isolation — the status:"pending" plus waitlisted:false interaction and the email/userId+courseId combination rule. It also clarifies that the status label describes 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?

Opens with a specific verb+resource ("List enrollment records on this site") and immediately scopes it ("who is enrolled or waitlisted in which course, and how far along they are"), including the default sort ("newest enrollment first"). It also draws a hard boundary against the closest sibling by stating applications are not enrollments and pointing to 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: application_list for applications awaiting a decision, and enrollment_update/enrollment_revoke to change or revoke a single learner's enrollment. It also enumerates the filter combinations (email alone = every course, email+courseId = the single enrollment, waitlisted true/false/omit) so the agent knows which call shape to build.

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 only declare readOnlyHint=false and openWorldHint=false, so the description carries the rest and delivers: omitted fields stay unchanged (PATCH semantics), non-enrolled learner yields a not-found error, no email is sent, and the return shape is listed. These are real behavioral traits beyond the annotation set.

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-loads what the tool does, then alternatives, then the waitlist recipe, then the return contract. Every sentence is doing work, though the middle paragraph is dense and could be split for scanability.

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 spelling out the returned object fields. Combined with the partial-update rule, error case, and side-effect disclosure (no email), an agent has everything required to invoke this mutation 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% and the schema already documents each field thoroughly, so the baseline is 3. The description still adds cross-field meaning the schema does not state as a whole: the email-or-userId identification rule, and the isWaitListed:false + status:"completed" combination that self-waitlisted learners need. Not a full 5 because much of the field-level detail is restated.

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 (change/update) on a specific resource (one existing enrollment) and enumerates the three mutation surfaces (expiry, waitlist, status label). It explicitly contrasts itself with enrollment_create and enrollment_revoke, so an agent can distinguish it from siblings 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?

Gives explicit when-to-use ("every change to an enrollment that exists") and names both alternatives with their selecting conditions (enrollment_create to add, enrollment_revoke to remove). It also supplies a concrete workflow recipe for promoting a waitlisted learner, which is exactly the kind of 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 only cover the safety profile (readOnlyHint, openWorldHint=false), and the description adds real behavioral content: the returned shape, the fact that three distinct failure modes (missing document, another site's content, unreadable type) collapse into one identical not-found error, and that an unprefixed id is rejected as invalid. It stops short of disclosing text size/truncation limits for long documents, which is the remaining unknown for a fetch 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 purpose and the search/fetch pairing, and every sentence carries non-redundant information (id format, return shape, error semantics, alternatives). It is a dense single paragraph that could be split into shorter units for scanability, but nothing is 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?

Complete for a one-parameter read tool: an output schema exists so return values need no further explanation, and the description nonetheless names the return fields, covers the error and invalid-input cases, and routes to the correct sibling tools for course work.

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

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

Schema coverage is 100% and the single id parameter is already documented, so the baseline is 3. The description still adds value by stating the id must be passed "exactly as search returned it" and giving the concrete "course:..." prefix format, which clarifies the prefix requirement beyond the schema 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 and resource ("Read one result found via `search` as plain text with its public page URL") and explicitly positions itself as "the fetch half of the search/fetch pair," so an agent can separate it from search and from the course_* siblings without opening a schema.

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

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

Gives 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 for its settings record ... and course_content_get for its lessons as EditorJS blocks." The routing decision is fully specified.

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 (readOnlyHint=true, openWorldHint=false), and the description adds substantial behavior beyond them: max 10 results, results ordered by course name, slug-less courses are never returned, catalog-hidden courses still are, returns {id, title, url}, and the query is truncated at 200 characters. It does not mention pagination or ranking nuances, so it falls just short of the top.

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 return shape before constraints and the sibling contrast. It is dense and nearly every sentence carries information, though the length is on the higher side for a single-parameter tool.

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?

Output schema exists, so return values needn't be re-explained, yet the description still signals the {id, title, url} shape and the fetch handoff. Combined with coverage of filtering quirks, result cap and ordering, 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 practical meaning: the whole query is matched as one case-insensitive phrase (so multi-word intent is constrained) and recommends one or two distinctive words. That is real guidance beyond the raw schema string.

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 (search) and resource (this site's courses) plus the scope (keyword match). It explicitly distinguishes itself from siblings course_list ('not an inventory') and fetch ('the search half of the search/fetch pair'), so an agent can route correctly 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.

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

Gives explicit when-to-use (pair with fetch for citable text, use for linking/citing) and when-not (listing, counting or managing courses belongs to course_list). It also advises query shaping ('use one or two distinctive words') and notes the keyword-less alternative's tradeoff.

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