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 are minimal (readOnlyHint=false, destructiveHint=false, etc.), so the description carries the burden of behavior. It discloses key behaviors: tokens fall back to defaults, empty issuerName uses workspace name, logoUrl format restrictions, and detailed composition rules for layout/order/freeform. This goes beyond the schema and is highly informative. It does not mention the return format, but an output schema exists, so that gap is acceptable.

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

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

The description is dense but well-structured: it opens with purpose, then explains optionality, logo constraints, composition details, and plan requirement. Each sentence adds necessary information without fluff. Slightly longer than ideal, but every part 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?

Given the complexity of the tool (many nested tokens, positions, translations, etc.), the description covers the critical behaviors and constraints that are not obvious from the schema. It explains defaults, format limitations, and the freeform coordinate system. Combined with the schema's per-field descriptions, an agent has sufficient information to use the tool correctly.

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

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

Schema coverage is 100% and the schema already provides descriptions for tokens. The description adds meaningful semantics beyond the schema: it explains the fallback behavior, the composition model (how layout/order/freeform interact), and logo format constraints. This is valuable context that helps an agent correctly construct the parameters.

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 'Creates a certificate template' – a specific verb and resource that distinguishes it from siblings like update_certificate, get_certificate, and list_certificates. It also provides context about the tokens structure, making the scope 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 (it's a create operation) but does not explicitly contrast with alternatives such as 'use update_certificate to modify existing templates' or 'use get_certificate to retrieve one'. It does mention the plan requirement, which is a prerequisite, but not when to choose this over other 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 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 indicate this is a write operation (readOnlyHint false), not idempotent, and not destructive. The description adds valuable behavioral context: themes apply 'live', the token override semantics (concept as base, others override), and the plan requirement. It does not contradict annotations. It doesn't describe failure modes or return value, but the output schema likely covers that.

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 three sentences, well-structured, and front-loaded with the core purpose. It packs a lot of information about the token system without being overly verbose. Each sentence earns its place, and the structure is logical: purpose, token model, requirement. Slight improvement could be made by trimming minor details, but overall it's concise.

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

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

For a complex tool with nested token objects and many options, the description provides a strong overview: it explains the concept system, mode handling, and plan requirement. It doesn't enumerate every token property, but those are in the schema. It mentions the live effect on courses. The output schema is present, so return values are covered. Missing a note on how to handle customFonts, but that's in the schema. Overall, it's 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% at the top level, with descriptions for name, tokens, and customFonts. The tool description adds meaning by explaining tokens.concept (listing all seven options), tokens.mode (light, dark, auto), and how palette and darkPalette work as overrides. This goes beyond the schema's generic description and helps the agent understand the design model. It doesn't explain every token property, but the schema covers those.

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 and resource: 'Creates a theme'. It elaborates what a theme is ('the look every course assigned to it inherits, live'), making the tool's purpose unambiguous. It distinguishes from siblings implicitly by the verb 'creates', and no other sibling has a similar description.

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 mention when to use this tool versus update_theme, delete_theme, or other related tools. It does provide a prerequisite ('Requires the Scale plan or higher') and explains the token model, which gives context, but it lacks any guidance on when not to use it or which alternative to choose. No explicit comparison with siblings is 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 non-read-only mutation. The description adds valuable behavioral context: the new locale starts empty, and the operation requires the Scale plan or higher. It does not contradict annotations and provides useful entitlement and initialization behavior beyond the schema.

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

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

The description is two short sentences, front-loads the core action, and contains no filler. Every word earns its place: it states what is created, how it starts, and what plan is required.

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 creation tool with complete schema descriptions, a plan requirement, and an output schema, the description covers the essential context. It does not explicitly mention what happens if a duplicate locale is created, but the schema already notes that a course can have only one translation per locale, so this is not a critical 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%, with both courseId and locale already described clearly, including example values and the uniqueness constraint. The description does not add additional parameter-specific semantics, 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 uses a specific verb ('Starts') and a clear resource ('a new (initially empty) locale for a course'), making the operation unmistakable. It distinguishes itself from sibling tools like update_translation, get_translation, and delete_translation by framing this as the creation of a new, empty locale.

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 a new locale/translation should be created, as opposed to updating or deleting an existing one. However, it does not explicitly name alternatives or state conditions like 'use update_translation to modify an existing locale.' The Scale plan requirement is a useful prerequisite, not an explicit usage-vs-alternative guideline.

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

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

The description adds critical behavioral context beyond the annotations: the signingSecret is shown once and cannot be retrieved again, warning the agent to preserve it. Annotations already indicate this is a write operation (readOnlyHint=false), and the description complements rather than contradicts 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?

Two short, purposeful sentences. The first states the core behavior and the second flags a non-obvious, operationally important detail. No filler or redundancy; the most critical operational warning is placed prominently.

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 exists and the request schema is fully documented, the description covers the essential extra context an agent needs: registering a webhook and preserving the one-time signing secret. It is slightly sparse on why one would create a webhook, but the schema and annotation coverage fill the remaining 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?

The input schema has 100% coverage with descriptions for all three parameters, so the description does not need to explain them. It adds no parameter-level detail, matching the baseline expectation. The mention of signingSecret relates to the response, not the request 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 clearly states the verb 'Registers' and the resource 'webhook endpoint,' making the tool's purpose unambiguous. It distinguishes itself from the many sibling webhook tools (delete_webhook, update_webhook, get_webhook) by indicating creation. It is slightly terse but sufficient.

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 says what the tool does but not when to use it versus alternatives. It does not mention that creating a webhook is for receiving event notifications, nor does it contrast with update_webhook or list_webhooks. Usage context must be inferred entirely from the verb and tool name.

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

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

Beyond the annotations, the description adds valuable behavioral context: courses using the template fall back to the built-in default design and continue issuing certificates. It also discloses the Scale plan requirement, which is not present in the annotations. This meaningfully informs the agent of side effects and prerequisites.

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 is front-loaded, followed by the most important side effect and a requirement. Every sentence earns its place.

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

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

For a simple one-parameter destructive tool with annotations and an output schema, the description covers the essential behavioral context: what is deleted, what happens to dependent courses, and the plan requirement. 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 single id parameter is already well documented in the schema. The description does not add additional parameter-level meaning, 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 uses a specific verb and resource: 'Deletes a certificate template.' It clearly distinguishes this from sibling certificate tools like create_certificate, update_certificate, get_certificate, and list_certificates by naming the delete action and the target resource.

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 a certificate template needs to be deleted. It does not explicitly mention alternatives such as update_certificate for modifying a template, nor does it state when not to use this tool. The plan requirement is helpful context but not a usage-vs-alternative guideline.

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 indicate destructive and idempotent behavior, but the description adds valuable context beyond them: deleting a theme causes assigned courses to fall back to no theme, and the Scale plan requirement is disclosed. This gives the agent a clear picture of the operation's consequences without contradicting any annotation.

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

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

The description is three short sentences with no filler. The core action comes first, followed by the important side effect and the plan requirement. Every sentence earns its place.

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

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

With an output schema present, the description does not need to explain return values. The destructive side effect on courses and the plan prerequisite are both covered, and the annotations provide the safety and idempotency profile. This is complete enough for an agent to invoke the tool correctly.

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

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 well described as 'The theme id, as returned by list_themes or create_theme.' The description only says 'by id', adding no meaningful semantic value 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 opens with a specific verb and resource: 'Deletes a theme by id.' This immediately distinguishes it from update_theme, create_theme, get_theme, and list_themes. The added side effect about courses falling back to no theme further clarifies the intended operation.

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

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

The description implies the use case through 'Deletes a theme by id' and adds an explicit prerequisite: 'Requires the Scale plan or higher.' However, it does not explicitly name alternatives or state when not to use this tool, so usage guidance is adequate but not fully explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds the plan requirement ('Requires the Scale plan or higher'), which is a behavioral constraint not covered by annotations. It also clarifies the scope of deletion ('entirely'), providing context beyond the schema. This adds meaningful value without contradicting annotations.

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

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

The description is two short sentences with no redundant information. The action and key requirement are front-loaded, making it efficient and easy to scan. Every word contributes to clarity.

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 delete operation with an output schema present, the description covers the essential details: the action, the resource scope, and a plan prerequisite. The destructive and idempotent nature is already handled by annotations, so no additional behavioral disclosure is needed. It is complete for an agent to correctly invoke the 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 having descriptive text in the schema. The description adds no additional parameter-specific meaning, so the baseline of 3 applies as the schema fully documents the parameters.

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 ('Deletes') and a clear resource ('a locale entirely'), which directly identifies the tool's function. It distinguishes from sibling delete tools like delete_course by specifying 'locale' as the target, making it unambiguous for an agent to select the correct operation.

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 the context that this tool deletes a translation/locale and notes the Scale plan requirement, which indicates a prerequisite. However, it does not explicitly contrast with alternatives such as update_translation or list_translations, nor does it state when not to use it. The usage is implied rather than fully specified.

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

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

Annotations 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint), so the bar is lower. The description adds valuable behavioral context: the Scale plan requirement and the fact that the zip is base64-encoded, plus the existence of a streaming alternative. This goes beyond annotations without contradicting them.

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

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

Two sentences with no wasted words: the main behavior, output format, streaming alternative, and plan requirement are each addressed in a front-loaded, direct manner. The description earns its place without redundancy.

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

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

Given the annotations, 100% schema coverage, and an output schema, the description covers all non-obvious facts an agent needs: the plan requirement, the bulk-migration recommendation, and the base64 zip format. Nothing essential is missing for correct invocation.

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

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

All four parameters are fully documented in the schema (100% coverage), so the baseline of 3 applies. The description adds no parameter-level details beyond the schema, but none are needed since courseId, track, locale, and version already have clear descriptions.

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

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

The description uses the specific verb 'Builds' with the resource 'SCORM package for a course' and clearly states the output format (.zip base64-encoded). This differentiates it from siblings like import_scorm and gives an agent a precise understanding of 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 explicitly provides a when-not condition: for bulk migration, prefer GET /api/v1/courses/:id/scorm, which streams the zip instead. It names the alternative and the reason to choose it, so an agent can correctly route between the two without further inference.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and idempotentHint=false, covering basic write/network/non-idempotent behavior. The description adds value beyond annotations by disclosing the asynchronous nature ('returns a job id immediately, writing takes tens of seconds'), the plan requirement, and the optional grounding in a URL. These are meaningful behavioral traits that help the agent set expectations. No contradiction with annotations.

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

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

The description is two sentences with no redundancy. The first sentence states the core action and optional grounding; the second immediately covers the async behavior, the required polling step, and the plan prerequisite. It is front-loaded with the most critical information and 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?

Given the tool's complexity (async, 5 parameters, output schema present), the description covers the essential operational contract: what it does, that it returns a job id, how to track completion (poll get_generation), and the plan requirement. It does not mention the output schema or list all optional parameters, but those are provided in structured fields. The description is sufficient for an agent to invoke the tool correctly and follow up appropriately.

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%, meaning every parameter already has a thorough description in the input schema. The description adds no parameter-specific information beyond what the schema provides; it only mentions 'optionally grounded in a URL' (which mirrors sourceUrl) and the async behavior. Since the schema carries the parameter documentation burden, a 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?

The description clearly states the core action: 'Starts writing a draft course from a prompt, optionally grounded in a URL.' The verb 'starts writing' and the resource 'draft course' make the purpose explicit. While it doesn't explicitly differentiate from the sibling create_course, the asynchronous generation concept is distinct and inferable.

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

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

The description provides explicit usage guidance: 'Returns a job id immediately — writing takes tens of seconds — then poll get_generation until status is completed or failed.' This tells the agent exactly how to handle the async flow and names the polling tool. It also mentions the prerequisite 'Requires the Build plan or higher.' It does not explicitly state when to avoid using this tool, but the guidance is clear 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the plan requirement, which is valuable beyond annotations. However, it doesn't describe the return format or error behavior, but with an output schema present, that is less critical. The description does not contradict annotations, and the plan requirement adds context.

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

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

The description is a single sentence that states the action and a key prerequisite. Zero waste, and the core purpose is front-loaded. It could not be more concise while still including the plan requirement.

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

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

Given that there is an output schema (though not shown in the input), the return value is already defined. The description covers the essential purpose and the one non-obvious requirement (plan level). It does not mention error cases or idempotency, but annotations cover idempotency. For a simple single-parameter tool, this is nearly 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?

The schema covers 100% of the parameter (id) with a clear description: 'as returned by list_certificates or create_certificate'. The tool description does not add additional semantics beyond what the schema provides. Since schema coverage is high, 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?

The description states a clear verb ('Fetches') and resource ('certificate template by id'), making the purpose obvious. It doesn't explicitly differentiate from sibling tools like get_issued_certificate or list_certificates, but the id-based fetch is distinct enough. A minor gap is not naming the sibling alternative, but the purpose is still clearly stated.

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 mentions the requirement 'Requires the Scale plan or higher', which is a clear usage constraint. It does not explicitly state when NOT to use it or name alternatives, but the id-based fetch implies it's for when you have a specific id, which is implicit. Could be improved by explicitly saying 'use list_certificates to find ids first', but the plan requirement is useful.

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 behavior, so the description only needs to add contextual behavior. It does: it reveals the polling contract and the terminal statuses (completed with courseId, failed with error), plus the plan requirement. This goes beyond what annotations provide, without contradiction.

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

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

Two terse sentences: the first states the core action, the second packs the polling behavior and a requirement. Every word earns its place, and the most critical information (what to poll for) is front-loaded. No redundancy or 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?

The tool is simple (one parameter) and has an output schema, so the description needn't detail return values. It covers the essential usage pattern and requirements. The only minor gap is that it doesn't mention timeout or retry behavior, but that's not typically required for such a poll-and-check tool; otherwise it 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 is only one parameter, 'id', and the schema already documents it as 'The generation job id returned by generate_course' at 100% coverage. The description does not add any additional meaning about the parameter itself, 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 ('Fetches') and resource ('generation job'), clearly distinguishing it from the many other get_* tools like get_course or get_theme. The polling semantics also make it unambiguous that this is the status-check tool for asynchronous generation.

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 the intended usage pattern: poll until 'completed' or 'failed', which implicitly tells when to call it (after generate_course) and how to interpret results. It also notes the plan requirement, a key prerequisite. However, it does not explicitly name an alternative or state when not to use it, so it misses the top tier.

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 establish read-only, idempotent, non-destructive behavior; the description adds the meaningful access prerequisite ('Scale plan or higher') not present in annotations or schema. It does not describe error cases or return format, but output schema exists and safety profile is covered, so the added context is sufficient.

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 no filler; the core behavior is front-loaded and the plan requirement is a distinct, necessary detail. 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 one-parameter read-only getter, the combination of description, full schema, output schema, and annotations covers what an agent needs: what to pass, where the id comes from, the access requirement, and safety. No significant gap remains.

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 sole parameter id is fully documented in the schema (100% coverage), including where the value comes from (list_themes/create_theme). The description itself adds no parameter detail 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?

States a specific verb ('Fetches'), resource ('theme'), and selection criterion ('by id'), which separates it from list_themes (all themes) and mutation tools like create_theme/update_theme. The title is generic, but the description disambiguates it.

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 a clear usage context: retrieve a single theme when an id is available, and only on Scale plan or higher. It does not explicitly name alternatives like list_themes or update_theme, but the singular 'by id' and plan constraint make selection straightforward.

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

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

Annotations already cover the read-only, idempotent, non-destructive nature of the call, so the description does not need to restate those. It does add one useful behavioral detail beyond annotations: the Scale plan requirement. However, it does not disclose other behavioral traits such as error cases or response specifics, so it adds value but not rich context.

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

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

The description is two short, front-loaded sentences. The core action comes first, and the plan requirement is a necessary gate. Every word earns its place; there is no redundant or vague phrasing.

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

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

For a two-parameter read operation with full schema documentation and a rich output schema, the description plus input schema gives an agent everything needed to invoke it correctly. The plan prerequisite is present, and the safety profile is already captured by annotations.

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 courseId and translationId are already documented in the input schema, including the useful note that translationId is not a locale code. The description contributes no additional parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description states a specific action verb ('Fetches'), a concrete resource ('one locale's translated fields'), and the singular scope. This clearly distinguishes it from sibling tools like list_translations, and it is not merely a restatement of the name.

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 this tool: to fetch a single locale's translated fields. It also adds a meaningful prerequisite ('Scale plan or higher'), but it does not explicitly name alternatives such as list_translations for fetching all locales, nor does it state when not to use this 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it specifies the time window ('this calendar month') and explains the null limit semantics ('Null limit means the plan is uncapped'). This helps the agent interpret the data correctly, though it doesn't describe response structure—but the output schema is empty, so no additional detail is expected.

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 redundancy. The main information (what it returns) is front-loaded, and the second sentence adds an important edge-case clarification. Every word earns its place—no fluff or repetition.

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

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

For a no-parameter, read-only tool with an empty output schema, the description is complete. It states the time period, the metric (course views), the comparison to allowance, and the excess cost rate. It also handles the null limit edge case. An agent knows exactly what to expect and how to interpret the result.

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

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

The tool has no parameters, so the description doesn't need to explain any. Per the baseline for zero parameters, a score of 4 is appropriate since the description provides relevant context (what data is returned) but doesn't need to add parameter-specific semantics. It correctly avoids inventing parameters.

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 what the tool does: returns the current calendar month's course views against the plan's allowance and any excess cost at the published rate. It distinguishes itself from other get_* tools by specifying the exact resource (plan usage) and the specific metrics (views, allowance, excess cost). The 'null limit' clarification adds precision.

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 implicitly indicates when to use it—whenever you need plan usage for the current month. It provides clear context (this calendar month, course views, excess cost) but does not explicitly mention alternatives or when not to use it. Since it's a get_* for usage, the purpose is obvious, but explicit exclusions would elevate 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 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?

The annotations already flag this as a non-read, non-idempotent mutation, and the description adds meaningful behavioral context: it creates a draft, restores Underlayer exports exactly, salvages other packages with warnings about missing data. It also discloses the plan requirement. 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 sentences, all information-dense: main function, import-fidelity behavior, routing alternative, and plan requirement. No filler or repetition of the tool name.

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

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

For a two-parameter import tool with an output schema, the description covers behavior, warnings, prerequisite, and the alternative endpoint. The presence of an output schema means the response shape does not need to be restated, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (zipBase64 and title). The description reinforces that the zip is base64-encoded and that the result is a draft, but it does not add meaning 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 opens with a specific verb and resource: 'Creates a draft course from a base64-encoded SCORM .zip.' It also distinguishes this tool from the bulk import endpoint and clarifies the provenance-dependent behavior (exact restore vs salvaged import), so an agent can tell exactly what this tool does.

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

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

It gives an explicit routing rule: for bulk migration use POST /api/v1/courses/import/scorm, which implies this tool is for single imports. It also states a prerequisite ('Requires the Scale plan or higher'), making when and whether to call this tool 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 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 read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond this: events are ordered newest first, and the trail is deliberately narrow by excluding routine reversible actions. This helps an agent reason about what results to expect.

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

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

The description is compact and front-loaded: the primary purpose and ordering are stated first, and the deliberate scoping limitation follows in a second sentence. Every sentence earns its place without unnecessary 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 simple read-only listing tool with two optional paging parameters, an output schema, and full schema coverage, the description is complete. It covers what the tool returns, ordering, and the important scoping limitation, so an agent has everything needed 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 coverage is 100%, with limit and offset fully described including defaults and ordering. The description adds no additional parameter semantics beyond what the schema already provides, 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 the tool lists the workspace's security and compliance trail, newest first, covering who did what and when. It also proactively distinguishes itself from an activity feed by noting which routine reversible actions are excluded, making it easy to tell this tool apart from other list_* siblings.

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

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

The description gives clear usage context: this is the security/compliance trail, not a general activity feed. It explains that routine reversible actions aren't logged, which sets expectations for when audit events may be absent, though it doesn't name alternative tools or explicitly say 'use this when...'.

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 declare the operation read-only and idempotent, and the description adds beyond that by disclosing an access requirement ('Requires the Scale plan or higher') and clarifying the scope of returned data. This satisfies the bar of adding behavioral/operational context beyond the structured annotations.

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

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

Three short sentences each earn their place: the first defines the resource, the second eliminates the most likely confusion with a sibling tool, and the third states a binding prerequisite. It is front-loaded and free of filler.

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

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

For a no-parameter, read-only, idempotent list tool with an output schema available, the description covers everything an agent needs: what is returned, how it differs from the closest sibling, and the required plan level. Nothing essential is missing.

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

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

There are zero parameters, so the description has no parameter semantics to add. The schema coverage is 100% because the schema is empty, meaning there is nothing undocumented. The baseline of 4 for a zero-parameter tool applies; the description correctly focuses on the meaning of the returned resource instead.

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: 'Lists certificate templates' and immediately clarifies what a certificate template is (the design of the PDF a learner gets on passing). It explicitly distinguishes this from issued certificates and names the sibling tool list_issued_certificates, so an agent can reliably select the correct 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 when-to-use guidance: use this tool to list templates, not learner-issued certificates, pointing directly to list_issued_certificates as the alternative. It also provides a prerequisite: 'Requires the Scale plan or higher,' which is necessary context for selecting or attempting the call.

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

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

Annotations 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds some useful behavioral context such as the one-run-per-learner-per-course constraint and the included result fields, but it does not go beyond that.

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 tight sentences with the core behavior front-loaded and no filler. Every clause adds useful information about scope, output content, or filtering.

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, annotations, and fully documented parameters, the description is largely complete for invoking this read-only list tool. It could be more complete by pointing to get_completion as the singular alternative, but nothing essential to calling it is missing.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description only restates filtering by course, learner, or status without adding new parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb and resource: it lists learner runs, and adds meaningful scope by saying 'one per learner per course' and which fields are included. It is clear enough to differentiate from get_completion, though it does not explicitly name any sibling 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 implies when to use it — when you want learner runs with score, pass/fail, and progress — and mentions filtering by course, learner, or status. However, it does not explicitly say when to prefer this over get_completion or when not to use 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 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 this as read-only and idempotent. The description adds meaningful behavioral details beyond annotations: newest-first ordering, default limit of 50, no practical maximum, and case-insensitive search over name, email, or external id.

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 tight sentence front-loads the core behavior, then packs defaults, offset, and search behavior with zero 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?

With an output schema present and annotations covering safety, the description supplies the remaining needed context: ordering, pagination defaults, and search scope. Nothing required to invoke this tool correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description mostly restates schema content, only adding 'no maximum' and the newest-first ordering. This is useful but doesn't substantially extend the parameter documentation.

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') and resource ('learners'), plus an ordering guarantee ('newest first'). This clearly distinguishes it from singular tools like get_identity and from related list tools like list_members, which target a different concept.

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 listing context with pagination and search semantics, so an agent knows this is the tool for pageable learner enumeration. It doesn't explicitly name alternatives like get_identity or list_members, but for a simple list tool the context is sufficient and no exclusion is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuine behavioral detail beyond the annotations: results are limited to actually issued certificates and include the public serial. This enriches what the agent knows about the tool's behavior 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 purpose and the scope qualifier ('actually issued') come first, and the sibling distinction is packed into the second sentence. Every phrase 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 read-only list tool with a full output schema and all parameters documented, this description is complete. The sibling distinction removes ambiguity, and there are no missing prerequisites or behavioral caveats an agent would need 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% – every parameter has a meaningful description, so the structured data already explains limit, offset, courseId, and identityId. The description doesn't add parameter-specific detail, but it doesn't need to; baseline 3 is appropriate when the schema carries the burden.

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') and resource ('certificates this workspace has actually issued'), and adds a distinguishing detail ('with the public serial printed on each one'). It also explicitly contrasts with list_certificates, making it immediately clear what this tool does and does not do.

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

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

The description explicitly names the closely related sibling (list_certificates) and explains the distinction: issued certificates vs certificate designs. This gives an agent clear routing guidance without needing to inspect either schema.

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.