Underlayer

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

Annotations only indicate non-read-only and non-destructive. The description adds that the block is created at its defaults and gets a fresh id, plus a follow-up workflow (update_screen). This is valuable behavioral context beyond the minimal annotations, though it doesn't discuss side effects or permission requirements.

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

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

Two sentences, front-loaded with the core action and purpose, then the key contrast with update_screen. No wasted words; every clause 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 simple 3-parameter tool with an output schema, the description fully covers the what, when, and how it fits into the workflow. An agent has enough to decide and call it correctly.

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

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

Schema description coverage is 100%—each parameter already has a detailed description, including the type enum and mentions of 'at its defaults'. The description reinforces this but adds no new parameter-specific information. Baseline 3 applies.

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

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

Clear statement of action ('Appends one block'), the resource (a screen), and a distinctive trait (with a fresh id). It contrasts with update_screen (restate whole screen) and implicitly distinguishes from add_screen, so an agent can tell them apart without opening schemas.

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

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

Explicitly describes when to use this tool ('the quick path when you only want to add something') versus when not (rather than restate the whole screen), and names the alternative (update_screen). No ambiguity about the intended 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?

Annotations already indicate readOnlyHint false and destructiveHint false, establishing this as a non-readonly, non-destructive write operation. The description adds meaningful behavioral context by specifying that the course is placed 'at the end' of the collection, which is not inherent in the annotations. It does not contradict the annotations and provides additional behavioral detail 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?

The description is a single, concise sentence that clearly communicates the action and its placement. Every word earns its place, with no redundancy or filler, making it optimally front-loaded and easy to parse.

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 two-parameter mutation tool with an output schema present, the description adequately covers the core action. It does not explain return values (unnecessary given the output schema), but it omits explicit mention of constraints like uniqueness (though that is in the schema). Overall, it is complete enough for an agent to take action, though adding a note about duplicate behavior would push it to a 5.

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

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

The schema provides 100% description coverage for both parameters, with detailed notes on id (collection id from list_collections/create_collection) and courseId (course in workspace, appended at end, can appear only once). The description itself adds no further parameter meaning beyond what the schema already conveys, so it meets the baseline but does not exceed it.

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 'Adds a course to the end of a collection' clearly states a specific verb (adds), resource (course to collection), and the particular placement ('end'). It distinguishes from siblings like remove_course_from_collection and move_course_in_collection by indicating the action is addition at the end, not removal or reordering.

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 does not explicitly state when to use this tool versus alternatives such as move_course_in_collection or remove_course_from_collection. It relies on the tool name and schema hints (e.g., 'as returned by list_collections or create_collection') to convey context, but no direct usage guidance or exclusions are provided.

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 this is a mutating, non-idempotent operation. The description adds useful behavioral detail: it returns the created screen, includes the ids needed for update_screen, and explains that template seeding produces blocks with fresh ids. 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?

Two sentences with no filler. The action and resource are front-loaded, and the template and return-value context are packed efficiently into the second sentence.

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

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

With a complete input schema and an output schema present, the description covers what remains essential: the operation's effect, the optional template path, and the next-step relationship to update_screen. Nothing critical is missing.

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

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

Schema description coverage is 100%, and the schema already documents title defaults, courseId, and templateKey semantics. The description adds workflow context around template selection and return value, but it does not materially improve parameter-level understanding beyond the schema.

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

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

The description states a specific verb and resource: 'Appends a screen to a course.' It also distinguishes the tool from related siblings like add_block and update_screen by clarifying that it creates a screen and returns the ids needed for subsequent block filling.

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 workflow guidance by pointing to list_screen_templates for template keys and update_screen for filling blocks. It does not explicitly state when not to use alternatives such as duplicate_screen, so it stops short of a 5.

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

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

Annotations already declare destructiveHint and idempotentHint, and the description goes beyond them by explaining the partial-deletion behavior: it reports what was actually removed, which can be fewer than requested. This adds useful context about already-gone identities without contradicting 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?

Two sentences with no filler. The core action and capacity are front-loaded, and the important edge case about already-removed identities is stated efficiently.

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 output schema, full parameter schema coverage, and annotations covering destructive and idempotent behavior, the description provides the remaining key behavioral detail (reported actual removals). 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?

Schema description coverage is 100%, so the schema already explains ids and externalIds. The description loosely restates 'by our ids or by your own externalIds' but does not add substantially new parameter-level meaning beyond what the schema provides.

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 action ('Deletes up to 500 learners in one call'), identifies the resource (learners/identities), and names both id modes ('our ids or your own externalIds'). This is clearly distinguishable from the singular delete_identity sibling and from bulk_upsert_identities.

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 frames the tool as a batch operation for deleting up to 500 identities at once, which conveys the primary use case. It does not explicitly name alternatives like delete_identity for single deletions, so it lacks explicit if-then routing, but the bulk context is 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?

Annotations already signal idempotent and destructive behavior, and the description adds concrete context: re-sending an existing list does not duplicate, results include created/updated counts, and null or omitted name/email values clear fields. The only blemish is an internal contradiction between 'Omit to keep the name already stored' and 'leaving one out clears it,' which slightly undermines transparency.

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 description is three short, front-loaded sentences covering operation, batch size, idempotence, and return value. Every sentence earns its place; the schema descriptions handle the remaining 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 destructive batch operation, the description covers the 500-item cap, externalId matching, created/updated counts, and differentiation from upsert_identity. With annotations and an output schema available, this is nearly complete; the omit/null contradiction is the main 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 description coverage is 100%, so the baseline is 3, but the added array-level guidance directly contradicts the property-level descriptions: name/email say 'Omit to keep' while the identities description says 'leaving one out clears it.' This makes the actual parameter behavior ambiguous, so the description fails to add reliable meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Creates or updates up to 500 learners in one call.' It also states the matching key (externalId), making the tool's bulk upsert behavior unambiguous and distinguishing it from single-item upsert_identity and bulk_delete_identities.

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 conveys when to use this tool (bulk operations up to 500 learners) and the schema description explicitly contrasts it with upsert_identity: 'Unlike upsert_identity, name and email are written as sent, so leaving one out clears it.' It does not state explicit exclusions or decision rules, but the context is sufficient for an agent to choose this over the sibling upsert tool.

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 aligns with the annotations (destructiveHint=true, readOnlyHint=false) and adds a useful consequence ('the link stops working'). With annotations already covering the write/destructive nature, the description contributes only a modest extra detail, not a deep behavioral profile.

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

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

A single, front-loaded sentence conveys the action, object, and effect with no filler. Every word 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, destructive tool with annotations and an output schema, the description covers the essential behavior. Any missing details (like return value) are handled by the output schema, and the intent is clear.

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 fully describes inviteId with its purpose and sources, so the description adds no new parameter meaning. Baseline 3 is appropriate given schema coverage is 100%.

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 verb ('Withdraws'), a specific resource ('a pending invite'), and the resulting effect ('the link stops working'). This distinguishes it from the related invite_member and remove_member tools without ambiguity.

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 targets 'pending invite' and explains the consequence, giving clear context for when to use it. However, it does not explicitly name alternatives like remove_member or state when not to use this tool, so it stops short of a full exclusion.

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real value beyond them: a plan gate ("Requires the Build plan or higher"), the fallback-to-default behavior of every token field, and the empty-issuerName-to-workspace-name rule. It does not cover failure modes such as duplicate names or whether a repeat call creates a second template, which keeps it short of a 5.

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

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

Information is front-loaded: creation, then defaults, then the logoUrl constraint, then composition semantics, then the plan gate. Dense but every sentence carries a distinct rule; the composition clause is slightly packed, costing a point.

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 an output schema present, return values need no explanation, and the description covers the non-obvious creation-time constraints (plan requirement, defaults, image formats, coordinate system) for a 2-parameter tool with a very deep nested tokens object. What is missing, error and duplicate-name behavior, is minor.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema cannot: positions coordinates are page fractions inside the margin, x is the element centre, y its top, w its width, and freeform:true switches from layout to positions. It also documents the PNG/JPEG-only logoUrl constraint that the schema only expresses as a generic uri format.

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 ("Creates a certificate template") that cleanly separates it from update_certificate, get_certificate and delete_certificate in the sibling list. An agent can identify the operation without opening the schema.

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

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

The description explains defaults, format constraints and the plan prerequisite, so an agent knows the preconditions for calling it, but it never says when to choose create_certificate over update_certificate or how to handle an existing template. Usage is implied by the verb rather than spelled out.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds no behavioral context beyond restating 'creates'—it does not mention duplicate-name behavior, permissions, side effects, or whether creation can fail under particular conditions.

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 single short sentence with no filler, making it very readable and front-loaded. However, it is essentially a rewording of the title, so it is concise but not meaningfully informative.

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

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

Given the simple two-parameter schema, existing annotations, and the presence of an output schema, the description is minimally viable for invoking the tool. It still lacks guidance on uniqueness, naming expectations, or how this relates to sibling collection operations, so it is adequate but not complete.

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

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

Schema description coverage is 100%, with both 'name' and 'description' already documented clearly in the input schema. The description adds no parameter-level meaning, but the schema carries the full burden, so the baseline score of 3 is appropriate.

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

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

The description states the exact operation ('Creates') and the target resource ('a collection'), making the purpose clear and unambiguous. It does not explicitly distinguish this from sibling creation tools like create_course or create_theme, but the resource itself is already named.

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 no guidance about when to use create_collection versus related alternatives such as add_course_to_collection or update_collection. There are no stated prerequisites, exclusions, or contextual hints about the intended workflow.

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 the operation profile (readOnlyHint=false, destructiveHint=false), so the bar is lower. The description adds one meaningful behavioral trait: the course is created in draft state, not published. It also describes the screen structure. It does not discuss idempotency or post-create behavior, but this is adequate given the annotation coverage.

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

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

Two sentences with no filler. The core action is front-loaded ('Creates a draft course'), and the screen-shape note is relevant context. Every sentence earns its place for a tool whose complexity is handled by 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 tool with a large, fully-documented schema and an output schema, the description doesn't need to explain return values. It covers the draft status and the expected screen structure, which is sufficient for correct invocation. It could optionally point to list_block_types or add_screen, but those are already referenced in the schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so all parameters are already fully documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Creates a draft course.' The qualifier 'draft' clarifies the state of the created object and distinguishes it from update/delete/list operations. Mentioning the screen shape (id, title, blocks) also helps separate it from sibling tools like add_screen and add_block, which operate on existing courses.

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

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

Usage is implied by the verb and resource — an agent can infer this is the tool for creating a new course. However, the description gives no explicit when-to-use guidance, exclusions, or alternatives (e.g., generate_course for AI-generated courses, add_screen for adding screens later). The schema partially compensates, but the description itself is silent.

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 non-read-only, non-destructive, non-idempotent, closed-world. The description adds meaningful behavior beyond that: the inheritance/'live' propagation to assigned courses, the override semantics ('anything omitted stays the concept's own'), the auto mode meaning 'follow the learner', and a plan-tier requirement. It does not mention duplication or delete behavior, so not a full 5.

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

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

Dense but front-loaded: creation and inheritance come first, then token resolution rules, then mode/palette, then the plan gate. Every clause carries information, though the middle sentences pack several concepts tightly.

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 three-parameter tool with heavy nested objects and enums, the description supplies the mental model (concept-as-base plus overrides) that the schema alone cannot. An output schema exists so return values need no explanation, and the plan gate is disclosed. Minor gaps remain around naming conflicts and post-creation application to courses.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds genuine meaning the schema lacks: it explains that concept selects a base design and lists the concept names, clarifies that all other tokens override parts of the concept, and names the relationship between mode, palette, and darkPalette. This goes beyond restating field names.

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

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

Specific verb (creates) plus resource (theme) plus a functional gloss of what a theme is: 'the look every course assigned to it inherits, live'. This distinguishes it cleanly from create_course, update_theme, and list_themes in the sibling set.

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 states a prerequisite ('Requires the Build plan or higher') which is useful gating context, but never says when to create a new theme versus update an existing one or reuse a concept, and names no alternatives. Usage is implied by the create verb rather than explained.

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 non-read-only, non-idempotent, non-destructive behavior, so the bar is lower. The description adds genuinely useful context beyond them: the created translation starts empty, and a plan-tier requirement gates the call. It stops short of stating the failure mode when a duplicate locale is requested.

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

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

Two compact sentences with zero filler; the creation semantics come first and the prerequisite second. Every clause carries information.

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

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

With an output schema present, return values need no explanation, and annotations plus a fully documented two-param schema cover the rest. The plan requirement and empty-initial-state note round it out; only the duplicate-locale failure behavior is left unstated.

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

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

Schema description coverage is 100% and both parameters are documented in the schema itself, including the one-translation-per-locale constraint. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb (starts/creates) and resource (a new locale translation for a course), and adds the clarifying detail that it begins empty. It is clearly distinguishable from update_translation and delete_translation by the 'new (initially empty)' framing, though it does not name those siblings explicitly.

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

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

Provides a real prerequisite ('Requires the Build plan or higher') that helps an agent decide feasibility, but gives no guidance on when to use this versus update_translation, or what to do if the locale already exists. Usage is implied by the create semantics rather than stated.

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

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

Adds substantial context beyond the annotations (readOnly=false, idempotent=false): the signingSecret is returned only once and cannot be retrieved again, and there are environment and tier ceilings (Sandbox unsupported, Build=10, Scale=50). These are exactly the operational facts an agent needs and cannot get from structured fields.

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

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

Three tightly packed sentences: purpose first, then the critical one-time-secret warning, then limits. No filler, and the highest-risk information (store the secret immediately) is given prominent placement.

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?

An output schema exists, so return structure need not be described, yet the description still flags the one non-obvious return detail (one-time signingSecret). Combined with the availability and quota constraints, nothing material 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 100%, so the schema already documents url, name, and eventTypes with examples and validation rules. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Registers a webhook endpoint'), which cleanly separates it from delete_webhook, get_webhook, list_webhooks, and update_webhook siblings. It doesn't explicitly name an alternative, but the create action is 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?

Usage is implied by the create semantics and the availability constraint ('Not available on Sandbox'), which usefully tells the agent when the call will fail. However, there is no explicit when-to-use-vs-alternative guidance connecting it to update_webhook or the listing 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description goes meaningfully beyond that by disclosing the downstream side effect on courses (they fall back to the default design and keep issuing) and a plan-level authorization gate, which an agent could not infer from the annotations or schema.

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

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

Three short sentences, zero filler, with the core action front-loaded and the impact and prerequisite following immediately after. Every sentence carries information.

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

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

For a destructive, single-parameter tool with an output schema and full annotation coverage, the description supplies the two things annotations cannot: what happens to dependent courses and the plan requirement. Nothing needed 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?

Single required parameter with 100% schema description coverage that already documents the id and points to list_certificates/create_certificate as sources. The description adds no additional parameter detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Deletes a certificate template') that cleanly distinguishes it from the many other delete_* siblings (delete_course, delete_theme, delete_collection). An agent can identify the target of the operation without opening the schema.

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

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

It gives a prerequisite ('Requires the Build plan or higher') and a consequence ('Courses using it fall back to the built-in default design'), which is useful context. However, it never states when to choose this over update_certificate or what to do if a template is still in active use, so usage guidance remains implied rather than 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 signal destructiveHint=true and idempotentHint=true, but the description adds no behavioral context beyond the bare fact of deletion. It does not mention whether deletion is permanent, whether it cascades to contained courses, what authorization is needed, or how failures are handled.

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 single, direct sentence with no filler or redundant phrasing. It is front-loaded and appropriately sized for a one-parameter operation.

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 one-parameter delete with full schema coverage, annotations, and an output schema, the description is mostly adequate. However, it omits any detail about collateral effects, such as whether deleting a collection also deletes its contents or referenced courses, which is relevant for a destructive 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 fully documents the sole 'id' parameter, including its source via list_collections or create_collection, so schema coverage is 100%. The description offers no additional parameter meaning, but the baseline of 3 applies because the schema carries the semantic weight.

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 verb ('Deletes') and a specific resource ('a collection'), so an agent understands the operation. It does not explicitly distinguish itself from sibling tools like update_collection or remove_course_from_collection, but the delete action is unambiguous.

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

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

The description gives no guidance on when to use this tool versus alternatives such as remove_course_from_collection or bulk_delete_identities. It also provides no preconditions, caveats, or context about when deletion is appropriate.

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 merely restates the destructive nature already declared by annotations (destructiveHint: true). It adds no new behavioral context such as permanence, cascading effects, or failure conditions. Since annotations cover the destructive hint, the description contributes minimal value.

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

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

A single concise sentence that is front-loaded with the action. No wasted words. It is appropriately sized for a simple tool.

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

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

Given the simple nature (one parameter) and the presence of an output schema, the description is adequate. It covers the purpose and the parameter. It could mention side effects, but for a delete operation with destructiveHint, it's sufficient. Missing explicit 'permanent' but implied.

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 already documents the 'id' parameter with a clear description. The description's 'by id' adds no additional semantic meaning beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

States the verb 'Deletes' and the resource 'course', distinguishing it from other delete_* tools by resource. The method 'by id' is clear. It is specific and 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?

No guidance on when to use this tool versus alternatives. It doesn't mention any conditions, prerequisites, or exclusions. While the resource name distinguishes it, the description provides no usage 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the description's 'Deletes' adds no behavioral information beyond that. The description does not disclose potential side effects, permanence, cascading deletions, or permission requirements, all of which would be valuable 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?

The description is a single, front-loaded sentence with no filler or redundancy. It is concise enough to be immediately understood, though it is slightly under-specified for a destructive tool.

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

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

The tool is simple with a single fully documented parameter, a full output schema, and annotations covering destructive/idempotent behavior. Together, these provide enough context for an agent to invoke the tool correctly. The main missing piece—usage guidance relative to bulk_delete_identities—is already penalized under usage guidelines.

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

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

Schema description coverage is 100%, and the schema clearly explains that the id parameter is Underlayer's identity id rather than the externalId. The description itself adds no parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Deletes a learner identity.' This is clear and unambiguous about the core operation. However, it does not explicitly distinguish itself from sibling bulk_delete_identities, so it lacks explicit sibling differentiation.

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 no guidance on when to use this tool versus alternatives like bulk_delete_identities or how to avoid misuse. It does not mention that the id must come from list_identities or upsert_identity; that information appears only in the schema, not in the usage 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 cover destructiveHint=true, idempotentHint=true, and readOnlyHint=false, the description adds the key nuance that learner answers are retained. This is valuable beyond the structured annotations. It could go further by mentioning reversibility or effects on course structure, but it discloses the most critical side effect.

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

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

Two sentences with zero filler: the first states the primary action, the second adds a crucial caveat. Fully front-loaded and every word 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 simple destructive tool with full schema coverage, an output schema, and annotations covering idempotency and destructiveness, the description covers the main purpose and the most important side effect. Minor gaps like edge-case restrictions or impact on published content are not critical given the tool's simplicity.

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

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

Schema coverage is 100% and both parameters have clear descriptions. The description does not enrich the meaning of the parameters beyond what the schema already provides, so baseline 3 applies.

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

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

The description states a specific verb ('removes') and resource ('a screen from a course'), clearly distinguishing it from siblings like add_screen, update_screen, duplicate_screen, and reorder_screens. The additional note about learner answers reinforces the scope.

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

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

No explicit guidance on when to use this tool vs alternatives (e.g., update_screen to edit, duplicate_screen to copy, or hiding a screen). The learner-answers note is a behavioral fact, not a selection cue. The agent must infer usage solely from the name and title.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine value beyond that: the cascade consequence that 'courses assigned to it fall back to no theme' and the plan-level entitlement 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?

Three short sentences with zero filler, leading with the core action and following with consequence and prerequisite in order of importance.

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 annotations covering destructiveness/idempotency, an output schema present, and 100% parameter schema coverage, the description needs only to add side effects and prerequisites — both are present. Coverage is solid, with only minor gaps like explicit irreversibility wording.

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

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

Schema description coverage is 100% and the single 'id' parameter is already documented (including where it comes from), so the description's 'by id' adds nothing new. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource ('Deletes a theme by id'), and the target identifier is unambiguous. It is clearly distinguishable from update_theme/get_theme/list_themes via the verb, though it does not explicitly name any sibling to contrast against.

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 a prerequisite ('Requires the Build plan or higher'), which is useful usage context, but gives no guidance on when to delete versus update or on alternatives for preserving assignments. Usage is implied rather than spelled out.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the danger profile is covered structurally. The description adds two pieces of context not in the annotations: the deletion is of an entire locale, and it is gated behind the Build plan — real prerequisite information. It stops short of describing cascade effects on translated content or recoverability.

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

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

Two short sentences, front-loading the action and then the prerequisite. No filler; every clause carries information an agent needs.

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?

An output schema exists, so return values need no explanation, and the 100%-covered two-parameter schema is self-documenting. The plan prerequisite is covered, but the description never states what happens to content already translated into that locale, which is the main residual ambiguity for a destructive tool.

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

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

Schema description coverage is 100%, with both courseId and translationId documented in the schema itself (including the 'not its locale code' caveat). The description adds no parameter-level detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Deletes a locale entirely'), which distinguishes it from sibling deletes like delete_course or delete_block. It does not name a sibling alternative, but the resource is unambiguous given the input schema's translationId.

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?

Adds one concrete prerequisite — 'Requires the Build plan or higher' — which is genuinely useful gating context. However, it offers no guidance on when to delete vs. update_translation, or whether callers should verify with get_translation/list_translations first.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. However, the description adds no additional behavioral context beyond the basic action—such as permanence of deletion, impact on associated resources, or irreversibility. With annotations doing the heavy lifting, the description contributes no extra transparency value.

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 single concise sentence that accurately states the purpose without any fluff or redundancy. It earns its place by being the minimal necessary statement, though it could be slightly more informative without harming conciseness.

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 simplicity—one required parameter, full schema coverage, annotations covering destructive and idempotent behavior, and an output schema present—the description is adequate. However, it misses an opportunity to mention common relevant context, such as that the deletion is permanent or that the webhook stops receiving events immediately. The structured fields carry most of the informational burden, so the thin description is acceptable but not complete.

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

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

Schema description coverage is 100%: the 'id' parameter is described as 'The webhook endpoint id, as returned by list_webhooks or create_webhook.' The tool description itself adds no parameter-level meaning. Baseline of 3 is appropriate because the schema fully documents the parameter, and the description does not need to compensate.

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 'Deletes a webhook endpoint' clearly states the verb 'delete' and the resource 'webhook endpoint'. It unambiguously distinguishes itself from sibling tools like create_webhook, update_webhook, get_webhook, and list_webhooks. No ambiguity exists about what action this tool performs.

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 no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. While the name and description imply it is used when a webhook needs to be removed, the description itself offers no conditional context or routing to related tools. This is a minimal, single-purpose description without usage direction.

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 (which only set readOnlyHint false, etc.), the description discloses two key behaviors: the copy is placed immediately after the original, and every block receives a new id, making the copy independent in the player. This adds meaningful context about side effects and independence. It does not mention permission requirements or potential impacts on referenced resources, but for a duplication tool the primary behavior is well covered.

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 two sentences with no filler. The core action (copy placement) is front-loaded, and the behavioral note about new ids is relevant and concise. Every word 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?

The tool is simple with two required parameters and an output schema (not shown but present). The description covers what the tool does and a key behavioral outcome (independence). It does not mention prerequisites like course existence or validation, but those are implicit in the schema and typical for such operations. For a straightforward duplication tool, it is sufficiently complete.

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

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

Both parameters (courseId and screenId) have descriptive schema entries with 100% coverage. The description adds no additional parameter-specific meaning beyond what the schema already provides, so the baseline of 3 applies. It correctly implies the scope (course context and screen within it) but does not elaborate on formats or constraints.

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

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

The description states a specific verb ('copies') and resource ('a screen'), and specifies placement ('directly after the original'). It also clarifies that the copy gets new block ids, distinguishing it from simply moving or referencing a screen. This clearly separates it from siblings like add_screen (creates from scratch) or update_screen (modifies existing).

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 duplicate of an existing screen), but it does not explicitly state alternatives or exclusions. There is no mention of 'use this instead of add_screen for copies' or any condition where this tool should not be used. The guidance is implied through the verb and placement but lacks explicit 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the base64 encoding of the payload, the streaming alternative for bulk work, and the Build-plan-or-higher entitlement requirement. No contradiction with readOnlyHint, since packaging is a read/export 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?

Three short sentences, each carrying distinct information (output form, alternative route, plan gate), with the core purpose front-loaded. 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?

An output schema exists, so return-value details need not be repeated. The description covers the operation, its output encoding, the plan prerequisite, and the escalation path for bulk use, which is everything an agent needs 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 100%, so the schema fully documents all four parameters (track, locale, version, courseId) including the enum and default. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Builds a SCORM package for a course') and specifies the return form (.zip, base64-encoded). This clearly separates it from the sibling import_scorm and from generic course 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?

Gives an explicit condition and alternative: bulk migration should use the streaming REST endpoint instead. It does not name any sibling tool as an alternative, but the routing guidance is concrete and actionable.

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

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

Goes well beyond the annotations (which only mark it as a non-readonly, non-idempotent, open-world write). It discloses the asynchronous job-id return, the tens-of-seconds duration, the required polling step, the recurring quota model with concrete per-tier limits, and the specific failure mode once the allowance is spent.

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

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

Three tightly written sentences, front-loaded with what happens first (draft + job id), then the follow-up action, then the limiting constraint. No filler, and every clause carries actionable information.

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

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

For an async generation tool with an output schema and full-schema parameter docs, the description covers everything an agent needs: the immediate return, the polling contract, and the quota boundary. Nothing material is left for the agent to guess.

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

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

Schema description coverage is 100%, so the schema already documents prompt, locale, audience, sourceUrl, and screensTarget fully. The description's phrasing 'optionally grounded in a URL' mirrors sourceUrl without adding format or behavior detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Starts writing a draft course from a prompt, optionally grounded in a URL.' The 'draft'/'from a prompt' framing implicitly separates it from the manual sibling create_course, but the sibling is never named, so an agent must infer the distinction.

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

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

Gives clear operational context: use this to kick off generation, then poll get_generation until status is 'completed' or 'failed'. It names the follow-up tool and the terminal states. It does not, however, state when to prefer this over create_course or address what to do if the quota is exhausted beyond waiting.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior, so the safety profile is covered. The description adds a plan/entitlement constraint that isn't in any structured field, which is genuinely useful context beyond 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?

Two short sentences, front-loaded with the core action and immediately followed by the constraint. 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?

An output schema exists so return values need not be described, and the key constraint (plan level) is stated. It stops short of any error/not-found behavior, but for a simple single-id read that is a minor gap.

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

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

Schema coverage is 100% and the single 'id' parameter is already documented with a precise description ('as returned by list_certificates or create_certificate'). The description's 'by id' adds nothing beyond the schema, so baseline 3 applies.

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

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

Clear specific verb+resource: 'Fetches one certificate template by id'. The phrase 'certificate template' disambiguates it from get_issued_certificate and the list/create/update/delete siblings, though it doesn't name those siblings explicitly.

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?

Adds a real prerequisite ('Requires the Build plan or higher') that tells the agent when the call can succeed, but gives no explicit when-to-use vs. alternatives, e.g. get_certificate vs. list_certificates or get_issued_certificate.

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, so the safety profile is covered by structured data. The description adds that courses are returned in display order, which is a useful behavior beyond the annotations, but it does not disclose errors, absence behavior, or any other operational traits. With annotations carrying the safety burden, this is adequate but not rich.

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

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

One short sentence is front-loaded with the core action ('Fetches one collection') and immediately adds the most decision-relevant detail ('including its courses in display order'). There is no filler, redundancy, or unnecessary context.

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 get-by-id tool with one required parameter, full schema coverage, a comprehensive annotation set, and an output schema, the description covers everything an agent needs to select and invoke it correctly. Return content is already captured by the output schema, so the description need not enumerate response fields.

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

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

Schema description coverage is 100%, and the id parameter is already well documented as 'The collection id, as returned by list_collections or create_collection.' The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

Description states a specific verb ('Fetches') and resource ('one collection'), and adds the distinctive detail that courses are included 'in display order.' This clearly distinguishes get_collection from list_collections (all collections) and from create/update/delete mutations without needing to inspect 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 singular 'one collection' plus the id parameter makes the intended use clear: fetching a specific existing collection when its id is known. It does not explicitly say 'use list_collections to browse all collections,' but the contrast is strongly implied by the sibling names and the description's singular scope.

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 false, so the safety profile is covered. The description adds valuable context by specifying that the response includes the learner's answers keyed by block id, which is beyond what annotations provide. It does not contradict annotations and gives useful detail about the return content.

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 single, concise sentence that front-loads the action and resource. It contains no extraneous words and every phrase adds value, clearly stating what is fetched and what it includes.

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 get-by-id tool with an output schema, the description is complete. It tells the agent exactly what is returned (the learner run including answers keyed by block id) and the only required parameter is documented in the schema. There are no missing details that would prevent 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 100% because the sole parameter 'id' has a description already stating it is the completion id from list_completions. The tool description does not add any additional parameter semantics beyond that, so the baseline of 3 applies.

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

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

The description clearly states the tool fetches one learner run (completion) by id, and specifies that it includes the answers keyed by block id. This is a specific verb and resource, and it distinguishes from siblings like list_completions (which lists) and get_generation (which gets generation status). The purpose is unambiguous.

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

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

The description implies usage when you have a specific completion id, and the parameter description references list_completions as the source of ids, providing clear context. However, it does not explicitly state when to use this tool over alternatives or mention any exclusions, so guidance is implied rather than 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond 'fetches one course by id' – it doesn't mention 404 behavior, whether the course includes nested content, or any rate limits. With annotations covering the key traits, a 3 is appropriate.

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

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

One short sentence, front-loaded with the verb and resource. Zero wasted words. The description is appropriately minimal for a simple getter.

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-resource getter with one fully-documented parameter, an output schema, and annotations covering safety/idempotency, the description is nearly complete. It could mention what happens when the id doesn't exist (404 vs empty), but that's a minor gap given the output schema exists.

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

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

Schema description coverage is 100% – the id parameter is fully described in the schema ('The course id, as returned by list_courses or create_course'). The description adds no additional parameter meaning beyond what the schema provides. Baseline 3 is correct.

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

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

The description 'Fetches one course by id' clearly states the verb (fetches), the resource (one course), and the identifier (id). It is distinct from list_courses (which fetches multiple) and update_course/delete_course (which mutate). However, it doesn't explicitly differentiate itself from other get_* siblings, though the resource name makes that obvious.

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 usage: call when you need a single course by id. It doesn't explicitly state when not to use it or mention alternatives like list_courses for multiple courses. The context is clear enough for a simple getter, but no explicit guidance is given.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds state-machine semantics beyond that: the terminal states and what accompanies each (courseId on success, error on failure), which is genuinely useful for a polling tool. No rate-limit or backoff guidance, but the key behavioral trait is disclosed.

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

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

Two tight sentences with the primary action front-loaded and the polling instruction immediately after. No filler, every clause 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?

An output schema exists, so return-value documentation is not required, yet the description usefully notes the terminal states an agent will observe. Combined with annotations covering safety and a fully documented single parameter, it is nearly complete; only polling cadence is left implicit.

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

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

Schema coverage is 100% and the schema itself explains the id comes from generate_course. The description adds no additional parameter syntax or constraints. Baseline 3 is appropriate when the schema carries full responsibility.

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 ('Fetches a generation job') and frames it as the async counterpart to generate_course. An agent can tell what it does at a glance, though it does not explicitly distinguish itself from sibling get_* tools beyond the generation-job framing.

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

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

Gives clear operational guidance: poll until status is completed or failed. This tells the agent the calling pattern (repeated polling) and the terminal conditions. It stops short of naming any alternative tool or stating a polling interval, but the workflow context is explicit enough to act on.

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, fully covering the safety profile. The description adds no extra behavioral context (e.g., error behavior, return structure, or side effects) but is consistent with the annotations, so a 3 is appropriate given the lowered bar.

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 single, direct sentence that front-loads the action and resource. It contains no filler or redundant detail, earning its place perfectly for a simple getter.

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 output schema and safety annotations present, the description is complete enough. It could optionally mention the return type or require an existing id, but the output schema and schema description already cover those details, leaving only minor gaps.

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

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

Schema description coverage is 100%, and the id parameter's description already explains that it is Underlayer's id, not externalId, and where to obtain it. The tool description merely restates that the tool fetches by id, adding no meaningful semantic value beyond the schema, so the baseline 3 applies.

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

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

The description 'Fetches one identity by id' uses a specific verb and resource, clearly distinguishing this singular getter from siblings like list_identities (plural), upsert_identity, and delete_identity. The title 'Get identity' reinforces the purpose, leaving no ambiguity about what the tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives such as list_identities or get_workspace_info. There are no stated selection criteria, exclusions, or prerequisites, leaving the agent to infer usage from the name and parameters alone.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond those annotations: case and dashes are ignored, and the result is scoped to this workspace's issuance status. 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?

Three short sentences, each carrying distinct value: what it does, input normalization, and scope/interpretation. No filler or 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 simple single-parameter lookup tool with an output schema and strong annotations, the description covers the essential operational details: lookup key, input flexibility, and workspace scope. Nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is 100% and the only parameter is already well documented with an example and normalization rule. The description reinforces the same 'case and dashes ignored' detail but adds little beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb ('looks up') and resource ('one issued certificate') with a clear lookup key (serial printed on it). It also distinguishes itself from general certificate lookups by emphasizing workspace scoping, so an agent can tell it apart from get_certificate and list_issued_certificates.

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

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

Provides clear context for when to use it: when you need one issued certificate by serial and want to know whether this workspace issued it. It explicitly sets an exclusion ('not whether it is real in general'), though it does not name sibling alternatives directly.

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

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

Annotations already convey read-only, idempotent, non-destructive behavior, lowering the description's burden. The description adds useful context about what metrics are returned, but it does not disclose behavioral details such as aggregation timing, data freshness, or response shape. This is adequate but not rich.

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 two sentences with no filler. The first sentence compactly enumerates the counted categories, and the second adds valuable context about the dashboard provenance without redundant wording.

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, read-only metric tool with an output schema available, the description gives a complete mental model: what is counted, across what scope, and where the numbers come from. Nothing needed to invoke it correctly is missing.

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

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

The tool has zero parameters and the input schema fully covers that surface (100% coverage). With no parameters to explain, the description does not need to add parameter-level semantics; the baseline of 4 is appropriate.

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

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

The description opens with a specific verb ('Counts') and identifies the resource and metric categories: courses by status, learners, runs in progress/completed, and certificates issued. It clearly describes what the tool does, though it does not explicitly differentiate itself from similar siblings like get_usage or get_workspace_info.

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 phrase 'the numbers behind the dashboard's overview page' provides clear context for when this tool is relevant. It implies the tool is for overall workspace counts/statistics, but it does not mention when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the non-obvious entitlement requirement ('Build plan or higher'), which is genuine value, but says nothing about behavior on a missing id or insufficient permissions.

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

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

Two short sentences, the core action front-loaded and the prerequisite trailing. No redundant restatement of the tool name or title.

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?

An output schema exists so return values need no explanation, and annotations cover safety. Purpose, identifier source, and plan gating are all present; only failure modes (unknown id, no entitlement) are left unaddressed.

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

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

Schema description coverage is 100% and the sole id parameter is fully documented in the schema. The description's 'by id' adds no format or sourcing detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource with scope ('Fetches one theme by id'), which implicitly separates it from list_themes, create_theme, and delete_theme. It never names a sibling for explicit differentiation, so it stops short of a 5.

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

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

Usage is implied: call this when you already have a theme id and want the single record. There is no explicit when-to-use vs alternative guidance (e.g., 'use list_themes to discover ids'), though the plan-tier prerequisite is a useful gating note.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered by structured data. The description adds a genuine behavioral constraint the annotations don't carry – the plan prerequisite – but says nothing about behavior when the id is invalid or not found.

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

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

Two short sentences, front-loaded with the action and followed by the prerequisite. No wasted words.

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

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

An output schema exists, so return values need no explanation, and the annotations cover safety. For a two-param read tool with full schema coverage, the description is largely sufficient, though error/not-found behavior is unstated.

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

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

Schema description coverage is 100%, so both parameters (courseId, translationId) are fully documented in the schema itself. The description adds no syntax, format or usage detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: 'Fetches one locale's translated fields.' An agent can distinguish this from list_translations (plural, list) by the singular scope, though it never names the sibling explicitly. Clear enough to act on.

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 one piece of context – that the Build plan or higher is required – but gives no guidance on when to use this versus list_translations or get_course. Usage is implied rather than stated.

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

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

Annotations already declare the safe read-only/idempotent profile, so the description's job is to add domain behavior - and it does, explaining that paid plans keep serving past the allowance and bill the excess while the sandbox has no overage rate and stops serving entirely. That is genuinely useful operational context an agent could not derive from the structured fields. It stops short of covering freshness/latency or auth requirements.

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

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

Two sentences, front-loaded with the primary metric and then the consequential billing/serving behavior. Every clause earns its place, though the '(null)' aside is a small detour into output-shape detail that the output schema already covers.

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 zero parameters and an output schema present, the description need not document return values; it instead supplies exactly the missing context about how the number behaves across plan types. Nothing an agent needs to call and interpret this tool is absent.

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 takes zero parameters, so there is no parameter semantics for the description to carry; the baseline of 4 applies. The parenthetical '(null)' even pre-explains an output field for the sandbox case.

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 resource and metric: this calendar month's course views measured against the plan allowance, plus the cost of excess. That is concrete enough to distinguish it from list/get tools for courses, identities or certificates. It does not, however, differentiate itself from the nearby get_overview or get_workspace_info siblings, so the agent must infer the boundary.

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

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

Usage is only implied: a zero-argument, read-only tool whose purpose is self-evident from the name and description. There is no explicit 'use this when you need X' statement and no pointer to the closest alternative (get_overview) that might also report plan-level information.

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 the operation read-only, idempotent, and non-destructive. The description adds value beyond those annotations by disclosing that the response excludes the webhook secret, which is a meaningful behavioral detail an agent should know before invoking the tool.

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

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

A single, front-loaded sentence conveys the purpose and a key limitation with no wasted words. Every element earns its place, and the structure is 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?

For a simple get-by-id tool with a full input schema, a complete output schema, and comprehensive read-only/idempotent annotations, the description covers the only additional caveat (no secret). Nothing an agent needs to correctly invoke the tool is missing.

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

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

Schema description coverage is 100%, so the 'id' parameter is fully documented in the schema itself. The description's 'by id' adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific action ('Fetches one webhook endpoint by id') and resource, distinguishing it from list_webhooks (which lists many) and create/update/delete operations. The parenthetical 'no secret included' adds a useful, differentiating characteristic.

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 the tool: when you need a single webhook endpoint identified by id. However, it does not explicitly contrast this with list_webhooks for retrieving all endpoints or mention alternative tools for related operations, so the guidance is only implied rather than 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the behavioral context that it confirms scope, which is useful but not extensive. It doesn't describe return format or potential errors, but with annotations covering safety, a 3 is appropriate.

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

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

One sentence, zero waste, and the key information (confirms workspace and plan) is front-loaded. Every word 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 zero-parameter read-only tool with an output schema and full annotation coverage, the description is nearly complete. It could mention what specific details are returned (e.g., workspace ID, plan name), but the output schema likely covers that. The description is sufficient for an agent to call it correctly.

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

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

The tool has zero parameters, so the schema is trivially complete. The description adds meaning by explaining what the tool returns conceptually (workspace and plan scope), which is valuable since there are no parameters to document. Baseline 4 for zero params is appropriate.

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

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

The description clearly states the tool's function: confirming the workspace and plan scope of the connection. It uses a specific verb ('confirms') and resource ('workspace and plan'), which is clear. It doesn't explicitly differentiate from siblings, but the unique scope (workspace/plan info) makes it distinguishable from the listed get_* 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?

The description implies usage context: use when you need to know the workspace/plan scope. It doesn't explicitly state when not to use it or name alternatives, but given the tool's unique purpose and zero parameters, the implied usage is adequate. No explicit exclusions or alternatives are provided.

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

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

Annotations cover only the safety profile (non-read-only, non-destructive, not idempotent), so the description carries the rest and does so well: it explains that Underlayer-exported packages are restored exactly while foreign packages are salvaged with limited fidelity and warnings, and flags the Build-plan requirement. This is exactly the behavioral context an agent needs before invoking.

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

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

Three tight sentences, front-loaded with the core purpose and the fidelity caveat, followed by routing and plan prerequisites. No sentence is filler.

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

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

With an output schema handling return values, the description covers purpose, input format, fidelity behavior, warnings, bulk alternative, and plan gating. An agent has everything needed to decide and to call correctly.

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

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

Schema description coverage is already 100%, so both parameters (zipBase64, title) are documented in the schema itself. The description adds no syntax, size, or format detail beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific verb (Creates), resource (a draft course), and input format (base64-encoded SCORM .zip) in the first clause. This clearly distinguishes it from create_course and generate_course, which produce courses by other means, and pairs naturally against the sibling export_scorm.

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

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

Gives explicit context for when to use the tool (restoring/migrating a SCORM package) and routes bulk migration to POST /api/v1/courses/import/scorm instead. It does not, however, contrast against sibling tools like create_course, so the routing is 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?

Annotations declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so this is a write operation. The description adds valuable behavioral context beyond annotations: the invite is not a direct add (async acceptance), and role limitations are explicitly stated. It does not contradict the annotations and enriches the agent's understanding of the side effects and constraints.

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

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

Two sentences with zero waste. The main action is front-loaded, followed by the crucial behavioral caveat (acceptance required) and a role constraint. Every sentence earns its place with distinct, non-redundant information.

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

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

For a simple tool with two parameters and an output schema present, the description covers the essential aspects: the invitation process, the email acceptance flow, and role limitations. It doesn't mention response details or potential errors, but the presence of an output schema and the tool's low complexity make these omissions acceptable. The description is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% — both parameters have descriptions. The role parameter's description already includes the constraint that owner can't be granted, which is also repeated in the tool description. The email description is standard. Since the schema fully documents parameters, the description adds no significant new semantic value, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Invites someone to the workspace by email.' It clearly distinguishes this from a direct add by stating 'this does not add them directly' and specifies the role limitation. This differentiates it from related membership tools like 'remove_member' and 'update_member_role' without ambiguity.

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 on how the invite works (email, acceptance required) and the constraint that only admin/member roles can be granted, with owner excluded. However, it does not explicitly name alternative tools or state when not to use this tool versus others like 'update_member_role' or 'cancel_invite'. The context is clear but no explicit exclusions or alternatives are given.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds critical security behavior: raw keys are hashed at rest and never returned, not even the caller's own key. It also clarifies the administrative boundary that this connection can list and revoke but not create keys.

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

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

Three focused sentences, no fluff or repetition. The purpose is stated first, followed by the security disclosure and the creation-context constraint; every sentence contributes meaning.

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 no-input tool with an output schema and rich annotations, the description fully covers the essential semantics: scope, returned fields, security behavior, and creation limitations. No additional information is needed for an agent to call it correctly.

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

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

The tool takes zero parameters, so the description has no parameter semantics to explain. Baseline for a zero-parameter tool is 4, and the description appropriately focuses on what the list returns rather than on any inputs.

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: list all API keys ever issued for the workspace, and names the returned fields (prefix, last use, revoked status). It also explicitly distinguishes itself from key minting, which is not possible through this tool.

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

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

The description makes clear this is the read-only listing operation and that key creation happens only on the dashboard, not here. It implies revocation is available through the same connection, though it does not explicitly name the revoke_api_key sibling as the alternative.

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, non-destructive and non-open-world, so safety is covered. The description adds genuine behavioral context beyond that: results are newest-first and the log is deliberately narrowed to exclude reversible actions, which shapes what an agent should expect to receive.

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

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

Two tight sentences, front-loaded with what the resource is, followed by the scoping caveat. No filler, no repetition of schema or annotation 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?

An output schema exists, so return values need no explanation, and both parameters are schema-documented. The low-complexity paginated list is well covered; only an explicit statement of when to prefer this over sibling listing tools is missing.

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

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

Schema coverage is 100% — limit and offset are fully documented in the schema, including defaults and paging. The description adds no parameter-specific syntax or guidance (it only echoes 'newest first'), so the baseline 3 applies.

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

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

The description gives a specific resource and scope: the workspace's 'security and compliance trail, newest first — who did what and when.' That clearly distinguishes it conceptually from activity/usage style tools, but it never names a sibling tool (e.g., get_usage, list_completions) to make the routing 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?

It implies when the tool is useful ('security and compliance trail') and states when content will be absent (routine reversible actions aren't logged), but there is no explicit when-to-use/when-not-to-use statement or named alternative. Usage has to be inferred from the scope description.

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 false, so the safety profile is covered. The description adds valuable behavioral context by warning that a block with wrong keys 'saves cleanly and then renders empty,' which is not evident from annotations. This helps the agent understand the risk of guessing and reinforces the need to call this tool.

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

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

The description is two sentences, front-loaded with the core purpose and a clear directive. Every sentence earns its place: the first states the function, the second explains when to use it and why. There is no fluff or 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 no-parameter, read-only listing tool with an output schema present, the description is complete. It tells the agent what to expect (block types and their fields), why to use it (avoid guessing), and the consequence of misuse. The presence of an output schema covers the return format details, so the description does not need to elaborate further.

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 baseline is 4 as per the rubric. The description does not need to explain parameters since there are none. It does mention 'fields each one reads' which hints at output content, but that is not parameter-related. The schema coverage is 100% (trivially), so the description adds no parameter semantics but also doesn't need to.

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: returns every block type a screen can contain, with the fields each one reads. It is specific with a verb ('list') and resource ('block types'), and it distinguishes itself from sibling tools like list_screen_templates by focusing on block types and their fields. The phrase 'Call this before writing screens' clarifies its role in the workflow.

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 guidance on when to use the tool: 'Call this before writing screens rather than guessing field names.' It provides a clear use case and even hints at the consequence of misuse (rendering empty). It does not explicitly name alternative tools or state when not to use it, but the context is strong enough for an agent to understand when to invoke it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description contributes a plan/entitlement requirement, which is genuinely useful behavioral context beyond annotations, but says nothing about volume, pagination, or ordering of the returned list.

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

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

Three short clauses, front-loaded with the verb and resource, then the disambiguation, then the prerequisite. No sentence is redundant and nothing is buried.

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

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

An output schema exists, so return-value detail is unnecessary in the description; the description instead supplies the one thing the schema can't — what the resource conceptually is and how it differs from a sibling. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes no parameters, so the baseline is 4. The description correctly avoids inventing filter syntax and instead spends its words on identifying the resource, which is the right trade-off for a zero-arg tool.

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

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

States a specific verb+resource ('Lists certificate templates') and immediately defines what a template is (the PDF design a learner receives), naming its components. It also explicitly excludes the near-neighbor resource by name, so an agent can distinguish it from list_issued_certificates without opening a schema.

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

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

Explicitly states the when-not case ('Not the certificates issued to learners; those are list_issued_certificates') and routes the agent to the correct alternative. It also adds a gating prerequisite ('Requires the Build plan or higher'), which is actionable selection 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the scope 'every collection', indicating no filtering, which is useful. It does not mention pagination or performance, but for a read-only list operation with annotations, this is adequate. It adds some context beyond annotations but is minimal.

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 single sentence with no redundancy. It states the core functionality immediately and front-loads the key information. No wasted words.

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

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

The tool has no parameters and an output schema is provided. The description is sufficient for an agent to know that calling it returns all collections in the workspace. It doesn't specify pagination, but for a simple list operation with an output schema, this is complete.

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

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

There are zero parameters, so the schema is fully covered. The description adds no parameter information because none exist. Per rubric, 0 parameters earns a baseline of 4.

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 function: listing every collection in the workspace. The verb 'lists' and resource 'collections' are specific, and the scope 'every' distinguishes it from get_collection (which retrieves a specific collection) and create_collection. It is unambiguous.

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

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

The description implies usage when the agent needs to see all collections. It does not explicitly mention alternatives or when not to use it (e.g., when a specific collection is needed), but the context of sibling tools makes the distinction clear. It lacks explicit exclusions but provides clear 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the data grain ('one per learner per course') and the in-progress/completed states, but says nothing about pagination behavior or ordering beyond what the schema already 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?

Two short sentences, with the purpose and data grain front-loaded ahead of the filtering hint. Minor redundancy: 'in progress or completed' restates the status enum and the same information appears in the output schema.

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

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

An output schema exists so return values need no explanation, parameters are fully documented in the schema, and annotations cover the safety profile, leaving little for the description to carry. The only real gap is routing against the sibling get_completion, which an agent must infer from the singular/plural naming.

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

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

Schema description coverage is 100%, so every parameter (limit, offset, status, courseId, identityId, identityExternalId) is already documented in the schema, including defaults and paging semantics. The description's filter sentence restates a subset of that without adding format or behavioral detail, so the baseline 3 applies.

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

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

States a specific verb (lists) and resource (learner runs), and defines the unit of the resource ('one per learner per course') along with the fields returned. It does not explicitly distinguish itself from the singular sibling get_completion, so it falls short of a 5.

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

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

The closing sentence 'Filter by course, learner or status' implies how to narrow results, which is implied usage rather than explicit guidance. There is no statement of when to use this instead of get_completion or list_identities, and no prerequisites are given.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds the 'newest first' ordering, a useful behavioral detail, but does not mention pagination or whether archived/draft courses are included.

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

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

A single, front-loaded sentence communicates the essential scope and ordering with no filler. Every word 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 no-parameter, read-only listing operation with an output schema available, the description provides all invocation-relevant information: what is listed, the scope, and the ordering. 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?

There are no parameters, so the input schema already fully defines the call surface. No parameter documentation is needed, and the baseline of 4 applies.

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

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

The description states a specific verb ('lists'), a clear resource ('every course in the workspace'), and an ordering ('newest first'). It is easy to distinguish from get_course, which fetches a single course, and from other list_* 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?

The description implies use when an agent needs the complete set of courses rather than a single course. It does not explicitly name alternatives or state when not to use this tool, so clear exclusions are missing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description adds the useful sort behavior ('newest first') that annotations do not convey, but says nothing about pagination semantics, total counts, or rate limits.

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

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

A single front-loaded sentence covering operation, ordering, and parameters with no filler. The em-dash clause paragraphs the parameter list efficiently, though it is dense enough to read as a run-on.

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 full output schema and rich annotations, the description only needs to cover operation and sort order, which it does. The remaining gap is routing context against the many list_* and get_* siblings, which is minor given the unique resource.

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

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

Schema description coverage is 100%, so the schema already documents limit, offset, and search in full. The description restates the same defaults and the same match fields, adding no syntax or format detail beyond the schema — the baseline of 3 applies.

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

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

States a specific verb and resource ('Lists learners') plus the ordering ('newest first'), which lets an agent distinguish it from get_identity and the other list_* siblings. It stops short of naming or contrasting with any sibling, so it is clear but not fully differentiated.

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

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

There is no when-to-use guidance, no mention of when to prefer get_identity, search_content, or bulk_upsert_identities, and no note on when to page versus filter. The only usage hint is implicit in the search parameter ('Omit to list everyone'), which is really a parameter rule rather than 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only that each record includes the public serial, and says nothing about pagination behaviour, volume of results, or authorization scope beyond the annotations' safety hints.

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

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

Two sentences, no filler, with the core scope stated first and the sibling disambiguation second. Every clause carries information an agent needs.

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 an output schema, full parameter coverage in the schema, and annotations covering safety, the description only needs to establish purpose and sibling scope, which it does. Remaining gaps (result volume, ordering guarantees beyond 'newest first' in the schema) are minor.

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

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

Schema description coverage is 100% and all four parameters (limit, offset, courseId, identityId) are documented with defaults and filtering semantics in the schema itself. The description adds no parameter-level meaning beyond implying the returned set is issued certificates, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Lists certificates this workspace has actually issued') and adds a concrete distinguishing detail (the public serial). It explicitly names the sibling list_certificates and how it differs ('lists certificate designs'), so an agent can pick correctly without opening either schema.

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

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

The description routes the agent between the two similar list tools by contrasting issued certificates with certificate designs, which is the key ambiguity. It stops short of stating explicit conditions such as when to filter by courseId or identityId, or when issued certificates are absent (e.g. revoked), so it is clear context rather than full when/when-not 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the behavioral detail that pending invites are included, which is useful context beyond the annotations. It doesn't mention pagination, ordering, or whether the response includes only active members vs all, but with annotations covering safety, a 3 is appropriate.

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

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

One sentence, 12 words, front-loaded with the resource ('Everyone in the workspace') and immediately adds the distinguishing detail ('plus any invites still pending'). Zero waste, every word 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 zero-parameter read-only list tool with an output schema present, the description is nearly complete. It tells the agent what the list contains (members, roles, pending invites). The only minor gap is not mentioning whether the list is paginated or ordered, but the output schema likely covers return structure. Given the tool's simplicity, this is adequate.

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 is trivially complete (100% coverage). The description adds meaning by specifying what the returned list contains (members with roles and pending invites), which is the only semantic content needed. Baseline 4 for zero-param tools is appropriate.

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

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

The description clearly states the tool lists workspace members with their roles and pending invites. It uses a specific verb ('list') and resource ('workspace members'), and the mention of pending invites distinguishes it from a plain member list. However, it doesn't explicitly differentiate from sibling tools like get_workspace_info or list_identities, though the resource is clear enough.

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 usage: call this when you need to see who is in the workspace and their roles, including pending invites. It doesn't explicitly state when not to use it or name alternatives like list_identities or get_workspace_info, but the context of 'workspace members' vs 'identities' provides some implicit guidance. No explicit exclusions or 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral value by stating that templates are structure not copy and that every block arrives empty—an important expectation for the agent. It doesn't describe output formatting, but the output schema and annotations lower that burden.

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

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

Three short sentences: core definition first, then usage pointer to add_screen, then the essential behavioral caveat about empty blocks. There is no filler, repetition, or irrelevant detail—each sentence earns its place.

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

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

For a zero-parameter list endpoint, the description covers what templates are, how they are grouped, how to use a returned key, and their empty-content trait. The output schema covers return structure. The only minor gap is that it doesn't explicitly say 'returns a list,' but the title and overall phrasing make that clear.

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 takes zero parameters and schema coverage is 100%, so there is no parameter burden for the description to carry. The baseline for zero-parameter tools is 4, and the description adds no parameter-specific detail because none is needed.

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 identifies ready-made screen layouts organized by family (present, interact, assess), clearly naming the resource and its structure. It doesn't explicitly use a verb like 'lists' or 'returns,' but the title plus 'Ready-made screen layouts' makes the purpose evident. It also distinguishes from siblings like add_screen by noting the keys are meant for that tool.

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

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

It gives explicit downstream guidance: 'Pass a key to add_screen to start from one,' which tells the agent how to use the results. The family groupings also help the agent pick a template category. It doesn't name alternatives or exclusions, but for a simple list tool the usage context is clear.

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