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

Beyond the annotations, the description richly explains behavior: duplicate members are reported as added, duplicates in one batch are first-wins, unknown groups produce a not-found error, and adding members can grant course access. It also discloses the required OAuth scope. This far exceeds the minimal annotation information.

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 well-structured, front-loading the core action and batch nature before covering idempotency, error semantics, side effects, and auth. Every sentence adds meaningful information, and the length is proportionate to the tool's behavioral complexity.

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

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

Given the tool's complexity, the description is highly complete: it explains batch behavior, idempotency nuances, duplicate handling, error semantics, the access-granting side effect, and required scope. An output schema exists, so return-value details are not the description's burden. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 0%, but the description compensates by explicitly defining both parameters: 'id is the group' and 'student_ids are obfuscated learner ids.' It also adds behavioral meaning to student_ids by explaining duplicate handling inside a batch. It could still go deeper on value formats or constraints, but the core semantics are covered.

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

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

The description uses a specific verb and resource: 'Add learners to a student group,' and immediately clarifies it is a batch operation. It clearly distinguishes itself from sibling tools like remove_group_memberships by naming the opposite action and the target entity.

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

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

The description gives clear operational context: it is a batch add, idempotent, requires the student-groups:write OAuth scope, and can grant course access. It does not explicitly name alternatives or state when not to use it, but the direct purpose and prerequisites make usage fairly 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?

The description richly discloses behavioral details: the unique key includes is_visible, contradictory rows can be created, duplicates are first-wins, unknown groups produce not-found errors, and success does not mean access changed. However, it states 'Idempotent' while annotations set idempotentHint to false, which is a direct annotation contradiction.

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 purpose is front-loaded in the first sentence, and the remaining paragraphs are well-structured around genuinely important caveats. The unique-key warning and idempotency explanation are necessary, not filler, and nothing repeats the 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?

For a batch mutation tool with zero schema-level parameter descriptions, this covers required fields, error behavior, duplicate handling, and OAuth scope. Since an output schema exists, not explaining return values is acceptable, leaving no meaningful completeness gap.

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

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

Schema coverage is 0%, so the description carries the full burden of parameter meaning. It explains that id is the group id and that overrides is a batch requiring published_course_id, not the course id, with optional is_visible true/false semantics. This adds substantial meaning beyond the bare schema.

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

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

States a specific verb ('Grant or deny') and resource ('group access to published courses'), and identifies itself as a batch operation. This clearly distinguishes it from the sibling visibility tools like list_visibility_overrides and remove_visibility_overrides.

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

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

The description implies the intended use case through the grant/deny semantics and batch framing, but it never explicitly says when to use this tool versus alternatives. It does not mention relevant siblings or exclusions, leaving tool selection partly to inference.

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

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

Annotations already indicate destructiveHint=true, but the description adds crucial behavioral context: irreversibility, no recovery or support path, destruction of name and email, gating by a confirmation header, and required OAuth scope/capability. This goes well beyond what the annotations alone communicate.

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

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

The description is longer than average, but the redundancy is justified for an irreversible destructive operation. It is logically organized: consequence, parameters, usage constraints, alternative, and authorization. A minor grammar hiccup ('sends and sends on nothing else') keeps it from being perfectly polished.

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

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

For a destructive, high-stakes operation, the description is complete: it covers irreversibility, parameter meaning, confirmation requirement, appropriate usage, the reversible alternative, and required permissions. The existence of an output schema means return-value documentation is unnecessary here.

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

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

Schema description coverage is 0%, so the description must carry the full burden. It explains that `id` is the obfuscated Skilljar learner id and explicitly states that `confirm=True` must be passed, which the schema only marks as a defaulted boolean. Both parameters receive meaningful semantic guidance.

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

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

The description clearly states a specific action ('PERMANENTLY ERASE a learner's personal data') and names the exact resource and effect. It also distinguishes itself from the reversible sibling `deactivate_student`, so an agent can tell them apart without inspecting 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?

It gives explicit when-to-use guidance: only when the user explicitly asks to anonymize a specific learner, and explicitly prohibits bulk requests, cleanup, or inference from course content. It directly names `deactivate_student` as the reversible alternative for removing access.

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 goes well beyond the annotations by disclosing non-obvious behavior: re-binding is a partial update, omitted fields keep current values, the first duplicate wins, unknown quiz_id fails the whole call, and unknown banks fail only their row. It also states the required OAuth scope.

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 longer than average but every sentence carries meaningful information. The key action is front-loaded, parameter details are compactly bundled, and the critical partial-update caveat is highlighted and elaborated.

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

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

The description is fully self-sufficient for an agent to invoke the tool correctly: it covers what the call does, parameter semantics, edge-case behavior, error handling, and authorization. The output schema exists so return-value detail is not required in the description.

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?

Despite 0% schema description coverage, the description thoroughly explains both parameters: quiz_id, the question_banks list, and each item's fields including order, randomize_questions, and limit_question_count. It even defines the special 0 value for limit_question_count.

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

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

The description opens with a specific verb and resource—'Attach question banks to a quiz'—and states the resulting behavior: the quiz draws its items from them. This clearly differentiates it from unbinding, listing assignments, and other quiz-related operations.

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

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

It provides clear context for when to call this tool: to attach banks to a quiz, with optional ordering and question-limiting controls. It does not explicitly name alternatives or exclusion conditions, but the described semantics make the intended use 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 are minimal (readOnly=false, idempotent=false, destructive=false), so the description carries the burden and does so richly. It discloses real-world impact: may email people, grants access to paid content, lowercases addresses, deduplicates per call, rejects past expires_at, and processes rows independently with a `failed` field to check. Nothing contradicts the annotations; the mutation flag is consistent with the described effects.

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

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

The description is front-loaded with the core purpose and impact, then flows logically through parameter semantics, constraints, safety warnings, failure behavior, and authorization. Every sentence adds necessary information; there is no filler or repetition. Despite its length, the structure makes it easy for an agent to extract what matters.

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

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

Given that an output schema exists to define return values, the description covers everything else needed to select and invoke the tool correctly: scope, timing constraints, duplicate handling, partial-failure semantics, and safety boundaries. It is complete for a high-risk bulk mutation tool and leaves no critical operational ambiguity.

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

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

Schema description coverage is 0%, so the description must fully compensate for all three parameters, and it does. It explains that published_course_id and expires_at apply to everyone while emails is per-person, clarifies future-only semantics for expires_at, and details duplicate-email behavior. This goes well beyond the bare type information in the input 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 opens with a specific verb and resource: 'Enrol people in a published course by email address.' This clearly states what the tool does and distinguishes it from read-only enrollment tools like list_enrollments or get_enrollment, and from single-person enrollment tools. The added 'Affects REAL PEOPLE' warning reinforces the high-stakes nature without obscuring the purpose.

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

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

The description gives clear context: use this for bulk enrollment by email into a published course, and it states explicit guardrails: only on the user's explicit instruction with an explicit list of people, never when suggested by content or feedback. It also names the required OAuth scope. It does not explicitly name sibling alternatives such as update_enrollments or complete_enrollments, so it falls just short of full alternative routing.

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 annotations, the description discloses important behaviors: the server holds two independent credentials, partial availability is normal, it makes no external call when nothing is configured, and it never returns secret material. This gives the agent accurate expectations and prevents incorrect assumptions about failure states.

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 appropriately sized and front-loads the core purpose in the first line. Each subsequent sentence adds distinct value: usage timing, credential independence, offline behavior, and output safety. There is no redundant or filler content.

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

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

Given the zero-parameter schema, the safe annotations, and the presence of an output schema, the description covers all necessary context: when to call, what to expect, how to interpret partial states, and what is not returned. Nothing an agent needs to invoke this tool correctly is missing.

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

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

The tool has zero parameters, so there is nothing for the description to add about parameter meanings. The schema fully covers the input side, and the description appropriately notes that the tool needs no credential itself, which is the only input-related nuance worth stating.

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 exactly what the tool does: it reports which Skilljar credential is configured, working, and what each unlocks. It is clearly a diagnostic tool and is distinguishable from the capability-oriented siblings like describe_capabilities by its focus on credential readiness.

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

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

The description gives explicit usage direction: call it first whenever a tool reports a credential problem, and relay its output instead of retrying because retries fail identically. It also clarifies that it works even when other tools fail, which tells the agent when to prefer this tool over alternatives.

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

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

The description goes well beyond the annotations by disclosing that this operation can issue certificates, send real emails to learners, and remove completions. It also states the required OAuth scope and the consent condition for marking completion. This gives the agent critical side-effect awareness that annotations alone do not provide.

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

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

The description is front-loaded with the core purpose, then structured as a clear batch-operation explanation with parameter semantics and warnings. Every sentence adds necessary information, and the formatting makes the critical send_notifications caveat prominent.

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 only two parameters, an output schema, and annotations, the description covers everything needed: parameter behavior, side effects, authorization, and user-consent constraints. There are no significant gaps that would prevent an agent from invoking 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 description coverage is 0%, but the description fully compensates. It explains send_notifications is required with no default and why, and it documents the enrollments item shape including id, completed_at, and success_status with their null semantics. This is far more useful than the minimal 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 opens with a specific verb and resource: 'Mark enrolments complete, or remove a completion.' It clearly distinguishes this as a BATCH operation, which separates it from single-enrollment tools like update_enrollments. The add/remove dual behavior is explicit, so an agent knows exactly what the tool does.

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

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

The description gives explicit when-to-use guidance: only on the user's explicit instruction, never based on course content or learner feedback. It also clearly explains that send_notifications must be false unless the user wants learners notified. It does not name alternative tools, though 'BATCH operation' provides some differentiation from siblings.

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

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

The description reveals important behaviors beyond the annotations: partial failures are normal, the failed field must be checked, ids are returned in creation order, new courses have no lessons and are unpublished/invisible, extra attributes are rejected rather than silently dropped, and OAuth scope courses:write is required. This goes well beyond the minimal annotation signals.

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 efficiently structured: purpose first, then batch/input shape, then failure semantics, then postconditions, then OAuth scope. Every sentence adds actionable information and there is no filler or repetition.

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

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

For a tool with a thin input schema and rich batch semantics, the description covers everything an agent needs: how to structure input, how to interpret partial failure, what the output fields mean, what state the new course is in, and what authorization is required. With an output schema present, no return-value detail 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 0% and the schema itself is extremely thin (courses array with additionalProperties true). The description compensates fully by specifying the required title field with length constraints, listing all optional fields, and explaining the rejection behavior for unknown attributes.

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

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

The description opens with a specific verb and resource: 'Create one or more courses' and immediately identifies the key distinguishing behavior—this is a BATCH operation. This clearly separates it from sibling tools like list_courses, get_course, and update_courses without needing to inspect the schema.

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

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

The description gives clear usage context: pass a list even for a single course, process rows independently, check failed before reporting success, and require the courses:write scope. It does not explicitly name alternative tools or state when not to use it, but the batch semantics and scope requirement provide strong practical guidance.

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

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

Beyond the annotations, the description discloses critical runtime behavior: case-sensitive uniqueness with a concrete failure example ('Partners' vs 'partners'), first-wins conflict resolution within a batch, per-row failure when category_id belongs to another organization, domain normalization ('bare domains like example.com (no @)', duplicates collapsed), and the auto-add learner side effect of rule_email_domains. This is far richer than the readOnlyHint/idempotentHint/destructiveHint flags and is fully consistent with them.

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 is front-loaded in the first two sentences, followed by cleanly separated sections for required constraints, optional fields, conflict semantics, and auth. Every sentence carries operational value — the case-sensitivity example, the 'no @' domain rule, and the first-wins rule each prevent real-world mistakes — with zero filler or repetition of schema content.

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

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

For a complex batch tool with one opaque parameter, the description covers the full item shape, validation rules, partial-failure behavior, intra-batch conflict resolution, and the required OAuth scope. Since an output schema exists, return values need no prose coverage, and nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 0% — the schema only declares 'groups' as an array of objects with additionalProperties allowed, revealing nothing about item shape. The description fully compensates by documenting every per-item field (name, category_id, rule_email_domains, send_course_enrollment_email) with types, character limits, ownership constraints, and behavioral effects, which is essential given the opaque 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 opens with a specific verb and resource ('Create student groups') and immediately adds the distinguishing batch nature ('This is a BATCH operation'). This cleanly separates it from group-related siblings like list_groups, get_group, update_groups, and delete_groups without requiring an agent to open their 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?

The batch framing and the explicit prerequisite ('Requires the student-groups:write OAuth scope') give clear context on how and when the tool is invoked. It stops short of a 5 because it never explicitly routes to alternatives for the when-not case, such as pointing to update_groups for modifying existing groups, but the intended usage 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 provide only generic hints (readOnly=false, idempotent=false, destructive=false). The description goes far beyond them by disclosing batch processing semantics, per-row independence, the need to check 'failed', the OAuth scope requirement, type-specific validation rules, and the append behavior for omitted 'order'.

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 every sentence and bullet carries actionable information. It front-loads the batch requirement, then organizes constraints by type, then covers optional behavior and error handling. There is no fluff or repetition of schema content.

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

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

Given the sparse schema and high payload complexity, the description is exceptionally complete: it defines the required shape of each lesson, the three supported types and their mutually exclusive content fields, limits, optional fields, ordering behavior, partial-failure handling, and required OAuth scope. An output schema exists, so return-value documentation is not needed here.

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

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

The input schema is minimal: a single 'lessons' array with additionalProperties:true and no item-level structure, so schema description coverage is 0%. The description compensates fully by specifying required fields, type-dependent content fields, constraints, and optional fields, giving the agent everything needed to construct valid payloads.

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

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

The description clearly states the verb ('Create') and resource ('lessons'), and explicitly identifies this as a BATCH operation. It distinguishes itself from sibling tools like list_lessons, get_lesson, and update_lessons by framing the batch nature and creation focus.

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

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

The description gives explicit usage context: pass a list even for a single lesson, required fields per lesson, type-specific content requirements, and behavior when omitting optional fields. It does not explicitly name alternatives or exclusion conditions, but the batch emphasis and write scope make the intended use clear.

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

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

The description discloses the one-time secret behavior, the fact it cannot be read back, the org-bound authenticated nature, that scopes are the only surviving control after a leak, and the required capability profile. Annotations only give generic hints, so this is rich, non-obvious behavioral context.

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

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

The description is organized into short, front-loaded paragraphs with a clear purpose statement, a critical sibling comparison, and all-caps warnings. Every sentence adds operational value and the formatting makes it scanner-friendly.

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 credential-creating tool with authentication requirements, scope selection, IP restrictions, and one-time-secret semantics, the description covers all non-obvious aspects needed to call it correctly. The output schema handles return-value documentation, so no additional output explanation is needed.

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?

With 0% schema description coverage, the description compensates well: it explains scope_codenames vs scope_preset (and warns against using both), explains ip_allowlist semantics, and points to list_oauth_scopes. It does not explicitly describe the name or description parameters, but those are self-evident.

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 'Create an API client BOUND TO THIS ORGANIZATION' — a specific verb, resource, and binding constraint. It also explicitly contrasts itself with register_oauth_client, so an agent can immediately tell them apart.

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

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

It gives direct guidance: 'Use this one unless you specifically need dynamic registration' and names the alternative register_oauth_client. It also states required auth conditions (clients:write scope, admin capability) and clear scope-parameter usage rules.

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 annotation flags (readOnlyHint/idempotentHint/destructiveHint all false) say little, so the description carries the transparency burden and delivers: batch semantics, the post-condition that a new bank is 'EMPTY and bound to nothing,' and the required 'question-banks:write' OAuth scope. It matches the annotations (a create operation is correctly not readOnly) and adds genuinely useful behavioral context beyond them.

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 compact sentences: purpose, per-item parameter contract, post-creation workflow, and auth scope. Each sentence earns its place and the critical purpose is front-loaded before the workflow detail.

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

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

For a single-parameter create operation with an output schema present, the description covers the essentials: what it does, the batch behavior, the exact item shape, the follow-up steps, and the permission required. Nothing critical is missing; the only minor gap is implicit partial-failure behavior for a multi-item batch, which is not disclosed.

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

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

Schema description coverage is 0% and the schema itself is thin ('additionalProperties': true on item objects), so the description must compensate — and it does by specifying that each item takes a single required attribute, name, with a max of 500. This materially narrows the agent's uncertainty about the runtime contract, though a concrete item shape example or explicit note that extra properties are rejected would have pushed it to 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?

The description opens with a specific verb and resource — 'Create one or more question banks' — and immediately flags the batch nature of the operation. It is clearly differentiated from its siblings (list_question_banks, get_question_bank, update_question_banks, delete_question_banks) and from create_questions, which the description itself references for the next step.

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

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

The description gives an explicit workflow: create banks here, then add items with create_questions and question_bank_id, then attach to a quiz with bind_quiz_question_banks. It does not explicitly state when NOT to use this tool relative to update/delete variants, but the workflow context tells an agent exactly where this tool sits in the lifecycle.

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 annotations only say the tool is not read-only, not idempotent, and not destructve — they carry no behavioral detail. The description adds substantial disclosure: batch semantics, service-assigned `order` being rejected, `is_graded`/`is_optional`/`answer_feedback_html` being rejected, and the surprising FITB behavior that every answer sent is stored as correct. These are exactly the kind of server-side behaviors an agent cannot infer.

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?

Every sentence carries call-correctness information that the otherwise-empty schema omits; there is no filler or boilerplate. The structure — purpose, parent rule, lifecycle, per-type table, answer shape, rejected fields, permissions — is logical and uses heavy formatting to aid parsing. It is long, but the length is justified by 0% schema coverage.

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 an empty schema and minimal annotations, the description covers the full call-shaping surface: required fields, parent exclusivity, per-type rules, limits, rejected fields, and permissions. The main residual gap is batch failure semantics — whether one invalid item fails the whole batch or is skipped — which matters for retrying a large create. The presence of an output schema reasonably covers return-value expectations.

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

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

Schema description coverage is 0% and the sole `questions` parameter is an opaque array with additionalProperties: true — the schema provides zero meaning. The description fully compensates: it defines required per-item fields (question_html, question_type, exactly one parent), the answer shape {answer_text, correct}, the answer_text length limit, and per-type answer 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 opening line 'Create one or more questions' states a specific verb and resource, and the explicit 'BATCH operation' marker distinguishes it from singular create/update tools. The create verb cleanly separates it from sibling list_questions, get_question, update_questions, and delete_questions without needing to open their 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?

The description gives clear guidance on the central usage decision — exactly one parent, quiz_id vs question_bank_id — with lifecycle consequences explained ('a question in a bank is reusable across quizzes; a question in a quiz belongs to it alone and is deleted with it'). It also states the required permission scopes. It does not explicitly name alternative tools or exclusion conditions, but for a create tool the parent choice is the key routing decision.

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 mark this as a non-read, non-idempotent mutation, and the description adds meaningful behavioral context: batch semantics, all optional field defaults, the empty-quiz behavior, and the required quizzes:write OAuth scope. This goes well beyond what the annotations alone convey. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then uses a compact, scannable list for defaults and a short note for the follow-up creation step. Every sentence or list item adds necessary information without padding.

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

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

The description covers what is created, how parameters behave, what a new quiz does not contain, and the required OAuth scope, with an output schema available for return shape. The main unaddressed detail is batch failure behavior, such as whether a partial failure creates some quizzes or none, which would be useful for an agent invoking a batch operation.

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

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

The input schema is extremely thin, with only a quizzes array and additionalProperties: true, so the description carries the full burden. It compensates thoroughly by documenting the required name field, max length, every optional field, defaults, alignment enum values, and the meaning of 0/null for limits and timeouts.

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

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

The description opens with a specific verb and resource: 'Create one or more quizzes.' It also identifies the operation as a BATCH operation, which distinguishes it from single-item or update/delete quiz siblings like update_quizzes and delete_quizzes. The purpose is immediately unambiguous.

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

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

The description clearly states this is a batch creation tool and provides concrete follow-up guidance: a new quiz has no questions, so the agent should use create_questions with quiz_id set. It does not explicitly contrast with update_quizzes, but the create-vs-update distinction is contextually obvious.

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 is highly transparent about the upsert and overwrite behavior, but the annotations declare destructiveHint=false. The description explicitly warns that existing answers are OVERWRITTEN with no warning and advises reading current values first if the old answer matters, which directly contradicts the non-destructive annotation. Per the rubric this is an annotation contradiction.

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 front-loaded with the core purpose and then adds only high-value caveats: batch behavior, overwrite warning, id semantics, error cases, and OAuth scope. Every sentence earns its place with no filler or repetition.

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

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

For a two-parameter tool with an output schema, the description covers all critical calling context: batch nature, single-learner scope, field-id vs value-id distinction, overwrite behavior, not-found error cases, and required scope. An agent has enough information to invoke 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 0%, so the description carries the burden, and it compensates well: it defines each item as {id, value}, clarifies that id is the signup-FIELD id, and states that student_id applies to all items. The value parameter's type/format is still left unspecified, which prevents 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?

The description opens with a specific verb and resource ('Set one learner's answers to signup fields') and immediately notes it is a batch operation. It later contrasts the field-id semantics with update_signup_field_values, so an agent can clearly distinguish this tool from its closest sibling.

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

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

The description explicitly names the alternative update_signup_field_values and explains the key difference: this tool uses signup-field IDs while the sibling uses signup-field-VALUE IDs. It also warns about common misuse and notes the required OAuth scope, though it does not give an explicit 'use this when...' 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?

Goes well beyond annotations by disclosing batch semantics, email lowercasing, duplicate handling ('FIRST occurrence wins'), and the OAuth scope requirement. These are behavioral traits an agent cannot infer from the name, schema, or 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 and batch nature, then parameter details, then behavior caveats, then the scope requirement. Every sentence adds distinct value 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?

For a single-parameter tool with an output schema present, this description covers purpose, parameters, edge-case duplicate behavior, the enrollment exclusion, and authentication scope. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema coverage is 0% and the students array items have no documented properties, yet the description fully compensates: it explains that each item needs an 'email' (required, lowercased), and that 'first_name' and 'last_name' are optional with a 50-char limit. This is exactly the meaning the schema is missing.

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 ('Register') and resource ('learners'), immediately clarifies it is a BATCH operation, and distinguishes its scope from enrollment by saying it does not enroll anyone. This is more than enough to tell it apart from siblings like bulk_enroll_students or update_students.

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 tells the agent when this tool is NOT the right choice: 'Registering an account does not enrol anyone in anything - use bulk_enroll_students for that.' It also implies creation-only use and provides a named alternative, giving clear routing guidance.

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

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

The description goes far beyond the annotations. It discloses that success only means the job started, that background workers fetch and re-host archives, that states can become PROCESSING or ERROR later, that there is no deduplication, and that each item triggers real egress with tighter rate limits. It also states the required OAuth scope. This aligns with readOnlyHint=false and idempotentHint=false.

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

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

The description is long but dense: every sentence adds a distinct, important behavior or constraint. Key warnings are front-loaded (async, success semantics, no dedup), and the structure moves from action to workflow to cautions to auth. 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?

For a complex asynchronous batch operation, the description covers the workflow, failure modes, polling guidance, no-dedup behavior, rate limiting, and authentication requirements. The output schema exists, so return-value details are not required. 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?

With 0% schema description coverage, the description fully compensates by explaining the item structure: each entry needs content_url as an https:// archive URL and a title of 1 to 500 characters. This is essential call-shaping information that the schema alone does not provide.

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

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

The description opens with a specific action and resource: 'Upload web packages from URLs.' It immediately distinguishes itself from sibling create tools by naming the resource type, and it clarifies the asynchronous nature of the operation. This leaves no ambiguity about what the tool does.

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

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

The description provides strong usage context: it tells the agent to poll get_web_package until READY or ERROR, to submit in small batches, and warns about rate limits. It does not explicitly enumerate alternatives or say 'use this instead of X', but the web-packages resource is unique among siblings, so the absence is minor.

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 annotations (destructiveHint=true), the description discloses crucial behavior: the endpoint uses a DELETE verb but is semantically a deactivation, the record survives with is_active false, already-issued tokens live until expiry, and the required OAuth scope and capability profile. This adds significant context that annotations alone do not provide.

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

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

The description is detailed but every sentence earns its place: core action first, id source second, the critical deactivation-vs-deletion warning, token behavior, companion tool, and permissions. The all-caps warning is justified by the DELETE-verb confusion.

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 mutating tool with gotchas, the description covers all necessary context: id provenance, non-deletion semantics, effect on current tokens, companion for immediate lockout, and auth requirements. Since an output schema exists, return value details are unnecessary.

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?

Although schema description coverage is 0%, the description fully explains the only parameter: 'id is the client's record id from list_oauth_clients.' This gives the agent exact sourcing instructions that the schema (just type: string) does not.

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

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

The description states a specific verb-resource pair: 'Turn an API client off. It can no longer obtain a token.' It explicitly distinguishes deactivation from deletion, and names the source of the id, making the tool's purpose unambiguous among OAuth client siblings like update_oauth_client and revoke_refresh_token.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it warns not to report the operation as deletion, and instructs pairing with revoke_refresh_token when immediate access termination is needed. This clearly routes an agent to the correct alternative for a different need.

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 flag destructive=true, but the description adds that this is a reversible soft delete, that records/history remain, that enrolments are NOT removed, and that specific OAuth scope plus capability are required. These are meaningful behavioral disclosures beyond 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 description is front-loaded with the core purpose and reversibility, then adds parameter semantics, exclusions, alternative selection, and auth. There is slight redundancy between 'reversible' and 'can be undone,' but every section otherwise earns its place.

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

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

For a single-parameter tool, the description covers what the tool does, what it does not do, how it can be reversed, when to prefer it, and required permissions. With an output schema present and destructive annotation present, nothing essential 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?

The input schema only gives `id` as a required string; the description explains it is the obfuscated Skilljar learner id, which is the key semantic needed to call the tool correctly. With 0% schema coverage, this fully compensates.

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

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

States the action (deactivate), resource (learner's account), and effect (removing access). The explicit contrast with `anonymize_student` and the reversibility note distinguish it from the closest sibling, so an agent can select it correctly.

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

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

Provides explicit routing guidance: prefer this over `anonymize_student` when the goal is to stop platform access because it can be undone. This is strong when-to-use direction with the alternative named, leaving little 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 far beyond the destructiveHint annotation by detailing what cascade deletion actually entails: memberships removed, published-course visibility overrides removed, potential loss of course access, learners not deleted, enrollments survive, and no undo. This is exactly the kind of behavioral context that annotations alone cannot 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?

The description is long but every sentence earns its place, given the irreversibility and cascading consequences. The key warning ('HARD DELETE AND IT CASCADES') is front-loaded, and the bulleted effects are scannable and precise.

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 tool's effect, scope, prerequisites, error semantics, alternatives, and safety implications. With an output schema present, return values do not need explanation. Nothing material is missing for an agent to invoke this safely and 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 0%, but the description fully compensates: it explains that group_ids takes obfuscated ids, each id is processed independently, and a 'failed' entry means the group still exists. This adds meaningful semantics above the bare array-of-strings 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 ('Delete student groups') and immediately clarifies that this is a hard delete that cascades, distinguishing it from soft-delete operations like quizzes and question banks. The scope is unambiguous and sets it apart from sibling delete 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 contrasts this tool with soft-delete alternatives and provides a concrete alternative ('rename it and clear its rule_email_domains') when the intent is reversible. Also notes the OAuth scope required. An agent can clearly decide when to use this versus other group-related tools.

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

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

The description is extremely transparent about the soft-unpublish behavior, noting that nothing is destroyed, enrollments survive, and republish reverses it. However, the annotations declare destructiveHint=true, which directly contradicts the description's core claim that 'nothing is destroyed.' Per the scoring rule, this contradiction forces a score of 1 and must be flagged as an annotation contradiction.

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 front-loaded with the most important clarification, then builds logically: what happens, what survives, how to reverse it, the preferred alternative, and auth requirements. Every sentence adds necessary value and there is no meaningful redundancy given the misleading tool name.

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

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

Despite the misleading name and minimal schema, the description covers the operation's true effect, parameter semantics, reversibility, alternative tool, scope requirement, and what is not affected. An output schema exists, so return-value explanation is unnecessary. The description is fully sufficient for correct invocation; the only inconsistency is in the annotations, not the description.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It completely compensates by explicitly defining id as 'the published-course id - the publication, not the course,' preventing the common confusion between a course id and a publication id.

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 clear, specific action: 'Remove a course from its domain' and immediately clarifies that this is a soft unpublish, not a deletion. It explicitly differentiates the publication id from the course and names the sibling unpublish_published_course as the same operation, making the tool's actual purpose unmistakable.

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

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

The description gives explicit usage guidance by stating that unpublish_published_course is the same operation under a better name and should be preferred unless a caller specifically expects this delete-named variant. It also states the required OAuth scope, which is essential for deciding when the tool can be invoked.

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?

Even though destructiveHint=true already flags danger, the description goes far beyond annotations by enumerating exactly what is deleted, removed, and untouched, including the critical side effect that quizzes become silently unbounded but remain deliverable. It also discloses permission requirements and instructs the agent to warn the user first.

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 longer than average, but every section earns its place: front-loaded summary, clear parameter instruction, bulleted side effects, and permission/consent guidance. The structure makes the destructive consequences immediately scannable.

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 destructive nature and the existence of an output schema, the description is complete: it covers the parameter, the full cascade of effects, what remains untouched, required capabilities, and the need for explicit user consent. No critical invocation information 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 0%, so the description must carry the weight. It adds meaningful detail by explaining that question_bank_ids is a list of obfuscated Skilljar bank ids, and the phrase 'one or more' clarifies batch semantics. It could go further on id format or validation, but for a single parameter this is solid.

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

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

The description opens with 'Delete one or more question banks,' a specific verb and resource, and immediately adds that it is destructive and batch. It clearly distinguishes this from sibling delete tools like delete_questions and delete_quizzes by naming the exact object type being deleted.

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

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

The description gives strong context: it is a batch operation, requires explicit user instruction, and requires specific capabilities. However, it does not explicitly mention a non-destructive alternative like unbind_quiz_question_banks when the goal is only to detach quizzes from a bank.

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 destructiveHint annotation, the description discloses consequential side effects: answers are deleted along with the question, the parent quiz or question bank is untouched, and answers are immutable elsewhere. It also explains the security model with the separate content.delete capability, adding significant behavioral context for a destructive operation.

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

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

Every sentence adds essential operational or safety information: batch semantics, ID format, cascade scope, the immutable-answers workflow, and required capabilities. The structure front-loads the destructive warning and keeps related details together without filler.

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

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

For a destructive, batch, security-sensitive tool, the description is complete: it covers the single parameter, side effects, exactly what is and is not deleted, required permissions, and the user-consent condition. An output schema exists, so return-value documentation is not needed here.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does so effectively. It explicitly names `question_ids`, states it must be a list even for one, clarifies the IDs are obfuscated Skilljar question IDs, and explains the cascade behavior affecting answers.

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

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

The description opens with 'Delete one or more questions,' a specific verb and resource, and immediately clarifies this is a BATCH operation. It also distinguishes the tool's scope from related delete tools by stating the parent quiz or question bank and every other question are untouched, so its purpose and boundaries are unmistakable.

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

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

The description explicitly says this is the only way to change a question's answers because answers are immutable on update, providing clear guidance versus the update tool. It also states required capabilities and instructs to take the action only on the user's explicit instruction, giving both when-to-use and when-not-to-use context.

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

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

Even though annotations already mark destructiveHint=true, the description adds substantial behavioral detail: which questions are owned versus shared, that question-bank assignments are removed but banks remain untouched, the separate content.delete capability requirement, and the instruction to act only on explicit user request. This goes far beyond the annotations and gives the agent a precise mental model of side effects.

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

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

The description is compact yet information-dense, with the most critical warnings front-loaded ('DESTRUCTIVE', 'BATCH operation'). The structured breakdown of deleted, removed, and untouched items makes complex side-effect semantics easy to parse without wasted words.

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

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

For a destructive batch operation with a single parameter and an output schema, the description is fully adequate. It covers required permissions, batch semantics, ownership rules, shared-bank exclusions, and the requirement for explicit user consent, leaving no critical gap for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the entire burden, and it fully compensates. It specifies that quiz_ids must be obfuscated Skilljar quiz ids, that a list is required even for one quiz, and that the operation is batch-oriented, all of which adds meaning beyond the raw array-of-strings 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 opens with 'Delete one or more quizzes', a specific verb and resource, and immediately flags the operation as DESTRUCTIVE and BATCH. It goes further to distinguish this from related deletion tools by spelling out exactly what is deleted, removed, and left untouched.

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

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

The description gives clear context for when this tool is appropriate: batch deletion of quizzes on explicit user instruction, with required auth scopes and capability clearly stated. It does not explicitly name sibling alternatives like delete_questions or unbind_quiz_question_banks, but its ownership explanation effectively tells the agent when quiz deletion is or is not the right operation.

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 goes well beyond the annotations by explaining that the delete is soft, that the package stops being listed, that existing references in unpublished courses are not rewritten, and that the call is refused rather than partially applied in live-use conflict cases. It also discloses the required OAuth scope. This gives the agent a clear model of the operation's behavior and failure modes.

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

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

The description is well-structured and front-loaded: the first sentence gives the essential behavior, and subsequent sections add necessary detail about id semantics, refusal conditions, soft-delete behavior, and OAuth scope. Each paragraph earns its place with no fluff or repetition.

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

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

For a destructive operation with one parameter and no schema-level parameter descriptions, the description is complete. It covers the core action, the single parameter's semantics, the conflict case, the soft-delete nature, the prerequisite steps, and the required OAuth scope. An agent has everything needed to decide when and how to call this tool.

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

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

Schema description coverage is 0%, and the description fully compensates by explaining that `id` is the obfuscated package id and that only one id is accepted, not a batch. This directly clarifies the sole parameter's meaning and constraints beyond what the schema's type/required fields provide.

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: 'Delete one web package.' It also clarifies that it is a single-package operation rather than a batch, which distinguishes it from potential batch operations and sets clear expectations.

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

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

The description clearly explains when the call is refused (when a live lesson uses the package) and gives the prerequisite action to resolve the conflict: unpublish the course or repoint the lesson first. It does not explicitly name alternative tools but provides strong contextual guidance for when this operation is applicable and when it is not.

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 annotations (readOnlyHint=true, idempotentHint=true), the description explains that even in read_write mode the tool itself does not execute writes—the plan contains paired create/delete steps. It also discloses that the plan reports refused steps, coverage gaps, and excluded tools. No contradiction with annotations.

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

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

Although long, the description is tightly organized with clear sections, bolded mode names, and bullet points. Every sentence adds necessary operational detail—execution order, coverage reporting, exclusions, final reporting, and the learner-account caution. 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?

For a tool of this complexity, the description covers purpose, mode semantics, execution instructions, reporting expectations, and safety constraints. The presence of an output schema means the return format need not be described in prose. The warning about tens of thousands of real people is a critical real-world detail.

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

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

The schema only shows mode with a default and no enum. The description fully defines both values: 'read_only changes nothing' and 'read_write also creates and deletes CONTENT', plus cleanup pairing. This is exactly the meaning an agent needs and goes well beyond the bare schema.

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

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

The description states precisely what the tool does: 'Return an ordered plan for demonstrating this server' and clarifies the plan is executed by the agent, not the tool. It distinguishes this meta-tool from the many sibling CRUD and read tools by explaining it returns steps rather than performing operations.

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

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

The description gives explicit instructions on how to use the plan: 'Call the tools it names, in order, substituting ids from earlier steps where a placeholder says so.' It also details mode-specific behavior, what the plan reports, and how to report results at the end. The warning about learner steps provides concrete guidance on what not to do.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond that: it explains the distinction between existing capabilities and enabled ones (available_but_disabled field), and states that the policy is immutable from this environment. This is valuable context not present in 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 description is concise and well-structured. It front-loads the core purpose, then immediately provides a usage directive, highlights the key field, and closes with a policy note. Every sentence carries meaningful information without redundancy or fluff.

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 zero-parameter tool with an output schema and annotations covering safety, the description is complete. It tells the agent what the tool does, when to call it (after refusal), how to interpret the critical output field, and what limitations exist (immutability). An agent would have no gaps in knowing when and how to use this 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?

The tool has zero parameters, so the schema provides full coverage and the description correctly does not attempt to document parameters. The description focuses on the tool's behavior and output interpretation, which is appropriate. Baseline for 0 params is 4, and nothing here warrants a downgrade.

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 clear purpose: describing what the install is permitted to do and what it could do if reconfigured. It uses a specific verb ('describe') and resource ('capabilities'), and distinguishes itself from siblings by focusing on permission introspection rather than access checks, problem reporting, or course listing.

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

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

The description gives explicit usage guidance: 'Call this after a refusal.' It also explains how to interpret the results, specifically telling the agent to inform the user of the setting to change when a capability is listed as available_but_disabled. It does not mention alternatives, but the context is clear and no alternative is needed.

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 say read-only and idempotent. The description adds substantial behavioral context: exact email matching, empty list on unknown addresses, v1's total semantics, the observed-but-undocumented id scheme, the separate v1 credential, and lifetime counts that v2 does not 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?

The purpose is front-loaded, and every subsequent line adds unique, actionable information: return fields, cross-API id compatibility, edge-case behavior, and auth requirements. There is no filler or repetition.

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

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

For a single-parameter lookup tool with an output schema, the description covers purpose, return contents, cross-API usage, failure behavior, credential requirements, and a caveat about id stability. 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?

The schema provides no description for email and coverage is 0%, so the description must compensate. It does: the parameter is clearly the lookup key, and the description specifies that matching is exact, adding meaning beyond the raw 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 opens with a specific verb and resource: 'Look up a learner by email, and get the id the progress tools need.' It clearly states what the tool does and distinguishes it from sibling tools by explaining how the returned id bridges v2's get_student and list_learner_progress.

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

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

It gives clear context: the returned id is needed by progress tools and works in both APIs, so an agent knows when to reach for this tool. It names relevant sibling outputs as destinations for the id, though it does not explicitly say 'use this instead of get_student when you only have an email.'

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 readOnly/idempotent annotations, the description thoroughly discloses behavior: the returned URL is a presigned link, valid for roughly an hour, requires no Skilljar credentials, changes every call, and grants anyone with the URL download access. It also surfaces the separate CSA_SKILLJAR_V1_API_KEY credential requirement.

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 front-loaded with the most important fact—working download link—and then organized into scannable paragraphs covering id semantics, link behavior, security caveats, alternative usage, and auth. Every sentence adds necessary context without padding.

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

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

Given an output schema exists, the description does not need to explain return shape. It covers id sourcing, link expiration, security handling, the alternative tool, and required credentials, making it fully sufficient for an agent to call this tool correctly.

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

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

Though schema coverage is 0%, the description fully explains the only parameter: 'id is the asset id, as list_assets returns and as a lesson's content_asset_id refers to.' This gives the agent concrete source semantics for the parameter beyond the bare schema.

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

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

The description states a specific verb and resource: 'Fetch one asset, INCLUDING A WORKING DOWNLOAD LINK.' It clearly distinguishes itself from list_assets by emphasizing the download link and by naming the alternative for cases where a link is not needed.

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 guidance is provided: use list_assets instead if you only need existence/type, because it returns no link. It also gives strong negative guidance about when not to use the returned link, such as not storing or caching it due to expiration.

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 indicate a safe read-only idempotent operation, but the description adds rich behavioral context: anyone holding the `code` can look up the certificate, `expires_at: null` means non-expiring rather than unknown, `score_as_percent: null` means no score rather than zero, and status reflects the certificate rather than enrolment. It also discloses the required `certificates:read` OAuth scope.

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 main purpose is front-loaded in the first sentence, and every subsequent sentence adds a distinct, non-redundant clarification about ids, codes, nulls, status, or scopes. The formatting with inline code identifiers keeps the details scannable without wasting words.

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

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

For a single-parameter read tool, the description fully covers the required parameter, key output semantics, authentication scope, and relationship to sibling tools. Since an output schema exists, the description does not need to re-explain return values, and nothing essential is missing for correct invocation.

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

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

The input schema provides no description for the `id` parameter, so the description carries full responsibility. It explains that `id` is the obfuscated certificate id returned by `list_certificates` and explicitly distinguishes it from the public verification `code`, which is exactly the semantic information an agent needs to populate the required parameter correctly.

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

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

The description opens with a specific verb and resource: 'Fetch one issued certificate, including its public verification code.' It clearly distinguishes the obfuscated certificate `id` from the public `code`, which prevents confusion with `list_certificates` and other certificate-related operations.

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

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

The description explicitly references `list_certificates` as the source of the `id`, and directs the agent to `get_enrollment` when the learner's progress is the goal instead of certificate status. It also clarifies that certificate status is independent of enrolment status, giving clear when-to-use and when-not-to-use guidance.

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

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

While annotations already declare readOnlyHint and idempotentHint, the description adds valuable behavioral context beyond those: it requires the courses:read OAuth scope, warns that the id is obfuscated and not a title, and explains edge-case handling (malformed, cross-organization, soft-deleted, or draft ids are reported as not found). This gives the agent concrete information about auth requirements and failure modes.

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

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

Four sentences with each earning its place: the core action, the added value over alternatives, the explicit exclusion of lessons with a pointer to the correct tool, and critical id/auth/error context. The most important information is front-loaded, and the description remains tight without redundancy.

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

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

For a single-parameter fetch tool, the description covers all essential operational aspects: what the tool returns, what it does not return, the exact format and semantics of the id, the required OAuth scope, and how failures are reported. The presence of an output schema covers return-field details, so nothing necessary 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?

The schema provides only a bare string type for 'id' with no description (0% schema coverage), so the description must carry the meaning. It does so explicitly: 'id is the obfuscated Skilljar course id, not a title.' This tells the agent exactly what value to supply and prevents common mistakes like passing a course title or human-readable identifier.

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

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

The description opens with a specific verb and resource: 'Fetch one course by its Skilljar id, with its full attributes.' It clearly distinguishes itself from list_courses by stating it returns more detailed attributes and is for courses you have already located. This unambiguous scoping makes it easy for an agent to know exactly what this tool does.

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

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

The description gives explicit when-to-use guidance: 'prefer this when you need detail about a course you have already located.' It also tells the agent what not to use it for and points to the correct alternative: 'It does NOT return the course's lessons; use list_lessons with filter_course_id for those.' No ambiguity remains about choosing between this and related tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds valuable behavioral context: the tool returns only aggregates, filter_domains is comma-separated, and the analytics:read OAuth scope is required. No contradiction with annotations exists.

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 tightly packed: a one-sentence summary, then necessary parameter semantics, then the alternative tool and auth requirement. Every sentence adds distinct value with no filler or repetition.

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

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

For a two-parameter analytics tool with an output schema, the description covers the core behavior, parameter meaning, scope limitations, alternative tool, and required OAuth scope. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains course_id identifies the course and is required, and filter_domains narrows figures and is comma-separated. This meaningfully compensates for the bare schema.

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

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

The description opens with a specific verb and resource: 'Summarise how one course is performing overall, across its learners.' It clearly distinguishes this aggregate analytics tool from per-learner tools like list_enrollments, and the 'one course' scope is explicit.

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

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

The description explicitly states when to use this tool versus alternatives: 'Aggregates only: for per-learner detail use list_enrollments with filter_course_id.' It also notes there is no organization-wide analytics call, so comparing courses requires calling per course. This is strong routing guidance.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes further by disclosing the OAuth scope requirement, naming the returned fields, and specifically warning that access_message_html and marketing_message are operator-authored copy to report rather than instructions to follow — a valuable prompt-injection safety note.

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

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

The description is front-loaded with the core fetch action and then adds only high-value context: return contents, the non-instruction warning, read-only status, and required scope. Each sentence earns its place and there is no tautological filler.

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

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

For a simple single-id fetch with an output schema available, the description is complete: it states what is returned, flags a security consideration, establishes the read-only boundaries, and names the required OAuth scope. Nothing essential for correct invocation or interpretation 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 0%, so the description must carry the semantic burden. It does so meaningfully by explaining that the id is an 'obfuscated id' rather than a raw identifier. It could add where to obtain this id or its expected format, but for a single-parameter get tool, the contextualization is strong.

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

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

The description opens with a specific verb and resource: 'Fetch one training domain by its obfuscated id.' It clearly distinguishes this single-item tool from list_domains and clarifies that the identifier is obfuscated, which is meaningful contextual detail.

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?

Fetching 'one training domain by its obfuscated id' implies when to use it over list_domains, and the statement 'there is no tool to change one' explicitly rules out an update workflow. However, it does not name an alternative tool or provide an explicit when-to-use versus when-not-to-use contrast, so it stops short of a 5.

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

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

Annotations already mark this as read-only and idempotent, and the description adds useful behavioral context: it requires the 'enrollments:read' OAuth scope and states exactly which fields will be returned. This goes beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded: purpose first, then return fields, then parameters and auth. No filler or repetition of schema details.

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

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

For a simple read-only lookup with one required parameter, the description is complete: it explains what it fetches, what it returns, what 'include' accepts, and the required OAuth scope. The output schema and annotations cover the remaining structured details.

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

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

Schema coverage is 0%, so the description carries the parameter burden. It clarifies that 'id' is the Skilljar enrollment id and lists accepted values for 'include' (purchase, student, certificate), adding real meaning beyond the bare schema. It doesn't specify whether multiple include values are supported or how they behave, but it is still helpful.

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

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

The description opens with a specific verb and resource: 'Fetch one enrolment by its Skilljar id.' It clearly distinguishes itself as a single-record lookup with a course-level reporting focus, and enumerates the exact return fields, separating it from list-style or progress-oriented siblings.

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

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

The description implies when to use it: when you need a single enrollment's score and progress rather than a list. It says 'one learner on one course', which frames the use case, but it does not explicitly name alternatives like list_enrollments or get_learner_progress.

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 mark this as read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond those annotations: it does not return the member list, v2 has no membership-read endpoint, the relevant timestamp is `updated_at` rather than `modified_at`, and the `student-groups:read` OAuth scope is required. This meaningfully shapes agent expectations.

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?

Every sentence earns its place: the fetch action, returned fields, the membership limitation, the timestamp clarification, and the authorization requirement. The most important information is front-loaded, and nothing is redundant or padded.

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

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

Given a single simple parameter, an output schema, and strong annotations, the description is fully sufficient. It covers what is returned, what is not returned, a subtle timestamp naming pitfall, and the required OAuth scope. No critical operational detail is missing.

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

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

The schema only declares `id` as a required string with no description, giving schema description coverage of 0%. The description compensates by specifying that the id is the group's obfuscated id, which is essential for correct invocation. It could add a bit more detail about the expected format or provenance, but for a single parameter this is solid coverage.

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

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

The description opens with a specific verb and resource: 'Fetch one student group by its obfuscated id.' It clearly identifies the action, the target, and the selection key, and it differentiates from list-style sibling tools. It also enumerates what the response contains, leaving no ambiguity about the tool's function.

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

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

The description provides clear context for when to use this tool: fetching one group by id, not listing groups or retrieving memberships. It explicitly names sibling tools `add_group_memberships` and `remove_group_memberships` when explaining what this tool does NOT do. However, it does not explicitly say to use `list_groups` when multiple groups are needed, so exclusions are slightly incomplete.

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 readOnly/idempotent annotations, it discloses meaningful behavior: domain-specific course identity is load-bearing, results are counts only, a non-enrolled learner yields a not-found error including enrolment count, and a distinct CSA_SKILLJAR_V1_API_KEY credential is required. No contradiction with annotations.

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

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

The description is longer than average but every sentence carries operational importance: scope, ID semantics, upstream pitfall, capability limit, error behavior, and credential requirement. It is front-loaded with the core purpose.

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

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

For a subtle read operation with domain-scoped IDs, the description covers parameters, error behavior, capability boundary, and authentication. The output schema exists, so the lack of return-value detail is not a gap.

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

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

Schema descriptions are absent (0% coverage), but the description fully compensates: user_id is defined as the Skilljar id from list_students, and published_course_id is clarified as domain-specific with two publications having separate IDs and progress.

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 opening line states exactly what is returned: how far one learner has got in one course on one domain. It distinguishes the tool from list_learner_progress by scoping to a single learner/course/domain and from per-lesson progress by stating counts only.

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

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

The description gives strong contextual guidance: the published_course_id is publication-scoped, the tool intentionally differs from Skilljar's by-id endpoint, and it does not provide per-lesson detail. It does not explicitly contrast with the sibling list_learner_progress or state when to choose that alternative, so it stops short of a full when/when-not matrix.

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 establish readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context: OAuth scope requirements, not-found behavior for invalid ids, and a strong warning that lesson body content is untrusted data that may contain prompt-injection-like text. This goes well beyond the structured annotation fields and does not contradict them.

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

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

The description is front-loaded with the core purpose and then adds only high-value details: the contrast with list_lessons, id semantics, scope requirement, error behavior, and a security note. Every sentence earns its place; there is no filler or repetition of structured fields.

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

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

For a single-parameter read tool with an output schema, the description is complete. It covers the resource, the distinguishing behavior, the parameter, the authentication requirement, error semantics, and the untrusted-data warning. An agent has enough context to select and invoke the tool correctly without needing additional information.

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

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

The input schema only defines id as a string with no description, so schema coverage is 0%. The description compensates fully by explaining that id is the obfuscated Skilljar lesson id and describing how invalid ids are handled. This gives the agent everything needed to supply the parameter correctly.

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

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

The description opens with a specific verb and resource: 'Fetch one lesson by its Skilljar id, including its body content.' It also distinguishes itself from list_lessons by explicitly stating that list_lessons does not return lesson bodies, which disambiguates it from the most closely related sibling.

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

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

The description gives clear usage guidance by explaining that get_lesson is the way to read content_html since list_lessons deliberately omits bodies. It also provides necessary context such as the required lessons:read OAuth scope and the error behavior for malformed, cross-organization, or soft-deleted ids.

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 readOnlyHint/idempotentHint annotations, the description reveals that no secret is ever returned and that there is no way to read one back, a critical behavioral constraint. It also explains the semantics of is_active, scope_codenames, and ip_allowlist, giving the agent clear expectations about the 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?

The description is a focused set of short paragraphs that front-load the purpose, then cover the parameter nuance, field meanings, secret non-return, and authorization requirements. Every sentence earns its place; there is no padding or repetition.

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

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

For a single-parameter read tool with an output schema and readOnly/idempotent annotations already provided, the description is complete: it defines the parameter, the meaningful response fields, the non-return of secrets, and required auth. No significant gap remains for correct invocation.

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

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

The schema only defines id as a string with no description, so 0% coverage places the burden on the description. The description fully compensates by clarifying that id is the internal record id from list_oauth_clients, not the OAuth client_id used for authentication, which is exactly the distinction needed to call this tool correctly.

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 opening sentence 'Inspect one API client: what it may do, and whether it still works' names a specific verb and resource, making the tool's function immediately clear. It distinguishes itself from list_oauth_clients by focusing on a single client, so an agent can tell which getter to use.

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

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

The description provides clear context by stating the required clients:read OAuth scope and admin capability profile, and it identifies the id source as list_oauth_clients. However, it does not explicitly contrast with siblings like update_oauth_client or list_oauth_clients with when-not statements, so the routing guidance is implied rather than fully explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context beyond those: the HTML fields are author-written markup to be treated as data, the returned object is the sequence rather than the publication, and a specific separate credential is required. These are valuable disclosures not present in annotations.

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

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

The description is front-loaded with the core purpose, then uses short, meaningful sentences for additional guidance. Each paragraph earns its place: the markup safety warning, the sequence-vs-publication distinction, and the credential note. There is no fluff or repetition.

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

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

For a one-parameter read tool with an output schema and strong annotations, the description is complete. It covers the primary purpose, the id semantics, a security-relevant field handling detail, the relation to a sibling tool, and an external prerequisite. An agent has enough information to invoke 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?

With schema description coverage at 0%, the description must clarify parameters. It says the tool fetches by id, establishing the id parameter as the learning path identifier. The parameter is simple and single, so this is sufficient, though the description does not specify id format or additional 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 opens with a specific verb and resource: 'Fetch one learning path by id, with its full descriptions.' It clearly identifies the operation and distinguishes it from related tools by noting that this returns the sequence, not its publication, and pointing to list_published_paths for visibility.

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

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

The description provides explicit usage context: use this for a learning path's sequence/full descriptions, not for publication status. It names the alternative tool, list_published_paths, for determining where the path is actually visible, which helps an agent choose correctly among siblings.

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

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

Beyond the read-only annotations, the description adds valuable behavioral context: the id is specifically the published-course id rather than the course id, the slug is null while unpublished because it is freed for reuse, and the required OAuth scope is stated. This is substantive disclosure that helps an agent understand what the call does and what it 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?

Every sentence earns its place: purpose, id clarification, key return-field semantics, and auth requirement. The information is front-loaded and tightly written 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?

With a single parameter and an output schema present, the description covers the essential context: id semantics, behavior of live and slug, and OAuth scope. Nothing needed 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 0%, so the description must carry the parameter documentation burden. It does so excellently by explaining that 'id' is the published-course id, not the course id, and illustrating the one-course-three-domains relationship. This provides meaning the bare schema cannot convey.

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

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

The description opens with a specific verb and resource: 'Fetch one course-to-domain publication and its access settings.' This clearly distinguishes the tool from list-oriented or mutation siblings, and the singular 'one' clarifies it is a single-record fetch.

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

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

The description gives clear context for when to use the tool: when you need one published-course by its published-course id. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5, but the context is unambiguous enough for an agent to select it correctly.

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 mark the call read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: the endpoint has no broader search capability, returned data concerns a real person's transaction and should be reported minimally, and a separate API key is required.

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 front-loaded with the core action and then gives practical guidance. It is somewhat verbose, repeating the no-listing/no-search point in several forms, but nearly every sentence contributes useful behavioral or credential 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?