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

No annotations are provided, so the description carries the full burden. It discloses that sign-in is required and that the tool returns public verification URLs, implying a read-only listing behavior. It does not describe exact output shape or edge cases, but for a zero-parameter list tool this is solid 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 description is one short, front-loaded sentence plus a parenthetical prerequisite. Every word adds value: the verb, the resource, the output detail, and the auth requirement. There is no repetition 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?

Given the tool's simplicity (no parameters, no annotations, no output schema), the description is sufficiently complete. It states what is returned (certificates with public verification URLs) and the key prerequisite (sign-in). It could mention empty-result behavior, but that is a minor gap for a simple list 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?

The tool has zero parameters, and the schema has 100% coverage of that fact. The description correctly does not invent parameter-related details. With no parameters to document, 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 uses a specific verb ('List') and a clear resource ('your earned certificates'), and further specifies the key output detail ('public verification URLs'). This makes its purpose immediately distinct from sibling academy_* tools, which cover lessons, quizzes, playbooks, and other resources.

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 imperative phrasing implies when to use it: when the user needs their earned certificates and verification URLs. The parenthetical '(Requires sign-in.)' adds clear prerequisite context. No explicit alternatives are named, but no certificate-related sibling tool exists, so this is acceptable.

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 readOnlyHint already covers the read-only nature, and the description adds useful behavioral context beyond that: the tool returns the full lesson text and is meant to be followed by tutoring, examples, and Q&A. That is sufficient for such a simple fetch operation.

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

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

Three concise sentences with no filler. The tool's purpose is front-loaded, and the tutoring-related sentences are useful instructional context rather than redundant prose.

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 lesson-fetch tool, the description is mostly complete: it states what is returned, how to use the content, and when to invoke it. It is slightly lacking in connection to the companion academy_lessons activity, so the overall flow is not fully explicit.

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 description adds no parameter-level meaning about level, slug, or locale. The input schema already documents slug and locale, but level remains just a number 1-6; this description neither clarifies nor compensates for that gap.

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 starts with a clear, specific action: 'Get the FULL text of one lesson.' It identifies the resource, scope, and output shape while distinguishing itself from list-style siblings like academy_lessons.

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?

'This is how a user takes the course with you as tutor' provides an explicit trigger for using the tool, and the teaching instructions clarify the expected interaction flow. It does not name alternatives or when-not-to-use cases, so it falls just 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?

With readOnlyHint: true already provided, the description adds that it returns only titles, descriptions, and duration, and that it excludes the body, which is useful behavioral context. It does not contradict annotations and adds specific information 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 sentence, perfectly concise, and front-loaded with the primary action and object. It also includes a necessary clarification about the body content. Zero 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?

Given that the tool is a simple listing operation with readOnlyHint, two parameters, and no output schema, the description is quite complete. It communicates what is returned and explicitly directs to a sibling tool for more detail. Some might expect mention of pagination or ordering, but this is a minor gap for a list 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 schema description coverage is 100% with clear parameter descriptions for both level (1-6) and locale (enums with defaults). The description does not add additional parameter semantics beyond the schema, so the baseline of 3 is appropriate since the schema already covers the parameter meaning.

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 all lessons in a level with titles, descriptions, and duration, and distinguishes it from academy_lesson by noting that the full text is not included. This directly addresses the purpose and differentiates from the sibling tool that provides full text.

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 (for a list of lessons) versus academy_lesson for full text, but it does not explicitly mention alternatives for other related tasks like searching or playbooks. The 'No body — call academy_lesson for the full text' provides a clear pointer to an alternative, but it lacks comprehensive when-not-to-use guidance for other siblings. Still, it clearly indicates context.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds useful context by revealing the fixed result shape (6 levels, title, subtitle, lesson count), going beyond the annotation without contradicting it.

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

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

Two sentences, no filler. The first states the action and result; the second gives the intended use case. Every word 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 simple read-only list operation with one optional parameter and no output schema, the description is complete. It states the fixed number of items and the fields returned, which covers the output shape adequately.

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% for the single optional locale parameter, including default and enum meanings. The description does not mention locale, but the schema fully covers parameter semantics, 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 uses a specific verb ('List') and identifies the exact resource ('the 6 curriculum levels') with the returned fields (title, subtitle, lesson count). This clearly distinguishes it from sibling tools like academy_lessons and academy_lesson.

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

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

The description explicitly states when to use it: 'Use to show the user the learning path and ask where they want to start.' It does not mention exclusions or alternative tools, but the context is clear enough for a simple list 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?

No annotations provided, so description carries burden. It mentions requires sign-in but does not disclose other behavioral traits like output format, side effects, or rate limits. Could be more transparent, but enough for a simple recommendation 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?

One sentence with parenthetical note, front-loaded with action, zero waste. Efficient and clear.

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 no output schema and no annotations, description covers main purpose and the rule, but lacks details on what the output looks like (lesson object? ID?), or how sign-in plays in. Still, for a simple tool, it's adequate but could mention response format.

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 has only one optional locale param with enum, but description doesn't explain its meaning or default behavior. With 0% schema description coverage, description compensates partially by indicating the recommendation logic, but does not add param-specific meaning. Since locale is optional and has enum, schema already provides choices, but default behavior missing.

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

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

Description states a clear purpose: recommend next lesson based on progress, with a specific rule (first incomplete lesson in lowest level). It clearly distinguishes from siblings like academy_lessons or academy_lesson by focusing on recommendation logic.

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?

Implies usage: call this to get recommended next lesson. Does not explicitly state when to use over alternatives, but the rule about progress and levels provides context. No exclusion or alternative mention.

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 readOnlyHint annotation already signals a read operation, and the description adds the 'full text' detail, which clarifies the return nature. However, it provides no context on response format, potential errors, or any special behaviors 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 a single, efficient sentence with zero filler. It immediately fronts the key verb and object, making it 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 retrieval tool with two parameters and no output schema, the description is adequately complete. The annotation and sibling context fill in remaining gaps, though it could additionally mention the response structure or the source of slugs.

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 50% (locale has a description, slug does not). The phrase 'by slug' gives the agent a hint that slug is the identifier, but the description does not elaborate on slug format or locale options beyond what the schema already provides. This adds minimal semantic value.

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 ('get') and resource ('playbook') with a clear scope ('full text', 'by slug'). It cleanly distinguishes from sibling tool 'academy_playbooks' (which likely lists playbooks) by focusing on a single entity.

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

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

The description implies usage when you have a slug, but it does not explicitly state when to choose this over siblings like academy_playbooks or academy_lesson. No alternatives or exclusions are mentioned, leaving the agent to infer the 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?

The readOnlyHint annotation already declares this as a safe read operation, and the description's 'List' wording is consistent. It adds useful context about the content being 'short, practical how-tos', but it does not disclose behavior such as ordering, pagination, or how category filtering interacts with the results.

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 one sentence, front-loads the core action ('List hands-on playbooks'), and adds only relevant context about content type and filtering. There is no redundant or filler language.

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?

This is a low-complexity read-only list tool with fully documented parameters and a readOnlyHint. The description sufficiently conveys scope and optional filtering; while it does not explain the exact return shape, the absence of an output schema is less critical for a simple listing action.

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 locale and category already documented. The description only reiterates the 'Optional category filter' concept and adds no new meaning about format, allowed values, or parameter interactions 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 uses a specific verb ('List') with a clear resource ('hands-on playbooks') and elaborates on the content type ('short, practical how-tos'). It clearly distinguishes the plural-list action from singular tools like academy_playbook, though it does not explicitly contrast with the similar-sounding academy_recipes.

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

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

The description states the basic action and mentions an optional category filter, but it gives no guidance on when to choose this tool over alternatives such as academy_playbook, academy_recipes, or academy_search. No when-not-to-use conditions or alternative suggestions 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?

With no annotations provided, the description carries the full burden. It transparently discloses the mutation and its effects (grants XP, updates streak, schedules spaced-repetition) plus the auth requirement. It omits edge cases like idempotency, but 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 the core action front-loaded and the prerequisite parenthetically. Every word contributes value; there is no 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 mutation tool with no annotations or output schema, the description covers purpose, side effects, and auth requirements. Parameter meanings are missing, but the overall usage context is sufficiently complete for a moderately simple 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?

The schema has 0% description coverage and the description provides no explanation of slug, level, or locale. It adds no meaning beyond the schema property names, which is a significant gap for a 3-parameter tool.

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

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

The description uses a specific verb-resource pair ('Mark a lesson complete') and enumerates distinct side effects (XP, streak, spaced-repetition) that clearly differentiate it from sibling tools like academy_quiz_submit or academy_review.

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 the usage context clear: it is for completing lessons. The sign-in requirement adds a useful prerequisite, though it does not explicitly contrast with alternatives or state when not to use the 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?

With no annotations, the description must carry behavioral transparency. It discloses that sign-in is required, which is useful. However, it doesn't describe what happens if the quiz is not available, if the lesson slug is missing, whether the response includes questions/answers, or any rate limits or side effects. It's a minimal disclosure 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 very concise (one sentence), front-loaded with the core purpose. The parenthetical about sign-in adds value without bloat. It is not over-specified, though it could include slightly more guidance 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 has 4 parameters (none required), no output schema, and no annotations, the description is too sparse. It doesn't explain how to construct a valid request (e.g., which identifiers are needed for which quiz types), nor does it hint at response structure. It mentions sign-in but not other requirements like completion status. For a complex retrieval tool, this falls short.

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

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

Schema description coverage is 0% and none of the 4 parameters are described in the tool description. While the names (slug, level, locale, lessonSlug) suggest meaning, the description does not clarify how they interact—e.g., whether 'slug' and 'lessonSlug' serve different purposes, or if 'level' selects a checkpoint. The description adds no parameter context, so it does not compensate for the coverage gap.

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 identifies the tool as fetching a quiz, specifying two concrete types ('lesson quiz or end-of-level checkpoint'). This distinguishes it from sibling tools like academy_lesson and academy_quiz_submit, though it doesn't explicitly differentiate from academy_review or academy_levels beyond the quiz focus.

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

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

The description gives a clear object and context but no explicit guidance on when to use it over siblings. It implies use for retrieving quiz content before submission, but doesn't state exclusions (e.g., not for submitting answers, which is academy_quiz_submit). It lacks alternative tool mentions.

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

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

With no annotations provided, the description takes on important transparency duties. It notes that sign-in is required, that passing a checkpoint issues a certificate, and that output includes per-question correctness and explanations. It does not mention whether submissions are repeatable or whether previous attempts are overridden, but it still provides meaningful behavioral context.

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

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

The description is compact, front-loads the action, uses an arrow to pipeline into expected results, and adds a prerequisite in a short parenthetical. Every clause adds useful information without bloating the text.

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

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

The description does a good job covering outcomes, certificate issuance, and auth, but it is incomplete on input semantics. Since there is no output schema and no parameter guidance, an agent would likely need prior context from sibling tools or conversation to construct valid slug and answers arguments.

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

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

Schema description coverage is 0%, and the description fails to explain what slug represents or how the answers object should be structured. The word 'answers' name, and the schema only says it is an object with string string values, leaving the mapping between quiz questions and responses ambiguous.

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 identifies a specific action, 'Submit quiz answers', and enumerates what the result includes: score, pass/fail, XP, per-question correctness, and explanations. It is distinct from sibling tools like academy_quiz, which likely fetches quiz content rather than performing submissions.

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 signals when to use this tool: when a user has quiz answers to submit and wants the scored result. It does not explicitly name alternatives or exclusions, but the generic language is unambiguous about the intended use case.

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 readOnlyHint annotation already declares this as a safe read operation. The description adds the useful constraint that recipes are English-only and notes it returns the full text, which adds value beyond the 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?

A single, front-loaded sentence conveys the purpose and a key constraint with 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?

For a simple retrieval tool with one parameter, read-only annotation, and no output schema, the description adequately covers the core behavior. It mentions full text and language limitation, though it does not specify output format or error cases, which are not critical at this complexity.

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

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

With 0% schema description coverage, the description must explain the slug parameter. It says 'by slug,' indicating slug is the recipe identifier, but provides no details on format or source. Minimal compensation but enough to understand basic usage.

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 it retrieves the full text of a build recipe identified by slug. This specific verb+resource distinguishes it from sibling tools like academy_recipes (likely a list) and other academy 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 this tool is for fetching a single recipe when you have its slug. It does not explicitly name alternatives, but the 'by slug' context clarifies when to use it versus listing tools.

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

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

Annotations declare readOnlyHint=true, and the description's verb 'List' aligns as a read operation. The description adds the context that recipes are English-only and mentioned content organization by phase, which adds value. There is no contradiction, and while it doesn't describe the return format, it provides some extra behavioral context beyond the annotation, though not extensively.

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

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

The description is concise at two sentences, front-loading the main purpose with a clear active verb. It efficiently conveys additional constraints (English-only, organization by phase). The main content is crisp without being overly verbose.

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 filtered-list tool with no required parameters and a single simple parameter, the description covers the essential context: what the tool returns, how it is organized, and the key limitation (English-only). The lack of output schema is acceptable since return values are not complex, and the description strikes an adequate balance for the complexity involved.

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 parameters with 'phase' already described as an optional phase number. The description reinforces the phase filter and adds the boundary (1-16), which duplicates schema info. No need for more, but the description does not add new parameter semantics beyond this.

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 build recipes as step-by-step guides, organized by phase, with a specific verb and resource. While it does not explicitly compare itself to siblings like academy_recipe, the description provides enough specific detail about what it returns to be useful, though the distinction from 'academy_recipe' could be clearer.

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 by mentioning the optional phase filter and the English-only constraints, which is useful context. However, it does not explicitly state when to use this tool versus alternatives like academy_recipe, nor does it provide explicit exclusion criteria or alternative tool references.

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

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

With no annotations, the description carries the full burden. It discloses the sign-in requirement and the read-only nature implied by 'List,' but it does not specify what happens if not signed in or whether any state is modified. This is minimal but adequate for a simple listing 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 extremely concise, consisting of two short sentences with no wasted words. It is front-loaded with the primary purpose and adds one essential constraint.

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 (no params, no output schema, no nested objects), the description is sufficient to understand its function. It could mention output details but none are critical for a list 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?

No parameters exist, so the description does not need to explain parameter semantics. Per the guidelines, zero parameters warrant a baseline score 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 tool's purpose with a specific verb ('List') and resource ('spaced-repetition items due today'), which effectively distinguishes it from sibling tools like academy_quiz and academy_review_grade.

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, nor any conditions or exclusions. The only usage note is 'Requires sign-in,' which is a prerequisite but not a comparative 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?

With no annotations, the description carries the burden. It discloses that the tool mutates state ('SM-2 interval update') and requires authentication ('Requires sign-in'), which is valuable. But it does not mention whether the action is reversible, what happens on invalid input, or what the response/return value is, leaving some behavioral gaps.

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 that packs purpose, grade options, the SM-2 update effect, and the auth requirement. Every word earns its place with no fluff.

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

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

Given the simplicity of the tool (2 params, no nested objects, no output schema), the description offers a solid baseline: purpose, action, and auth. However, it leaves id semantics and grading behavior underspecified, and does not mention alternatives, making it adequate but not fully complete for an agent selecting this tool.

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

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

The input schema has 0% description coverage, and the description only repeats the enum values ('again/good/easy') already present in the schema. It does not explain what 'id' refers to or how each grade value affects the SM-2 interval, so it fails to compensate for the missing schema 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 clearly states the action ('Grade a review item'), specifies the exact grade options ('again/good/easy'), and adds the functional context 'SM-2 interval update'. This distinguishes it from sibling tools like academy_review, which likely only fetches review items, and academy_quiz_submit, which handles quizzes.

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: this tool grades review items and updates SM-2 intervals, implying it is used after a review item is shown. It also notes the sign-in requirement. However, it does not explicitly mention when to prefer this over academy_review or other siblings, 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?

The description adds some behavioral context beyond the readOnlyHint annotation, such as returning ranked matches with snippets and ids. However, it does not mention pagination, result size, or edge cases. The annotation already covers safety, so the description provides moderate additional 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 description is two sentences, front-loaded with the action and scope, and ends with a clear usage cue. There is no redundancy or fluff, making it highly concise and well-structured.

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 lack of an output schema, the description adequately explains the return type (matches with snippets and ids). It also covers the scope (whole curriculum) and the use case. It does not mention limit behavior, but the schema covers that, so the description is fairly complete for an agent.

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 67% (query and locale have descriptions; limit has no description but includes min/max/default). The description does not mention any parameters, but the schema provides adequate semantics for a simple search tool. The description adds no extra parameter meaning, so a 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 clearly states the tool searches curriculum (lessons, playbooks, recipes) by keyword and returns ranked matches with snippets and ids. It distinguishes itself from sibling tools like academy_lessons or academy_playbook by specifying cross-content search, and from generic 'search' by its curriculum 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?

The description explicitly says when to use it: 'when the user asks about a topic and you want the most relevant material.' It provides clear context but does not explicitly state when not to use it or mention alternatives like specific retrieval tools (e.g., academy_lesson) or generic search for non-curriculum content.

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

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

With no annotations, the description carries the burden. It discloses that sign-in is required and itemizes the returned content, which is useful behavioral context. It does not describe the output format or possible side effects, but for a zero-parameter stats retrieval this is adequate.

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, front-loaded with the main subject, and lists the key stats without redundancy. The parenthetical about sign-in is a necessary addition.

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 is a zero-parameter stats getter with no output schema, the description sufficiently covers the returned data and authentication requirement. It could be more detailed about response structure, but it is complete enough 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?

The input schema has zero parameters, so the rubric baseline is 4. The description adds no parameter-specific detail but none is needed; it instead explains the tool's return content.

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 identifies the tool as returning Academy account stats and enumerates the specific data points (XP, rank, streak, lessons completed, badges, certificates, weekly league). This distinguishes it from sibling tools like academy_levels or academy_certificates, though it lacks an explicit action verb.

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 its use as the go-to for a summary of Academy account stats, and the sign-in requirement is a prerequisite. However, it does not explicitly state when to prefer this over siblings like academy_levels or academy_certificates, leaving the comparison implicit.

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?

No annotations exist, so the description carries the burden. It usefully discloses Pro-plan gating, sign-in requirements, and that the tutor is server-side with lesson context. It does not go further into error behavior or side effects, but for an AI-tutor query tool, the key constraints are made visible.

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 and every clause earns its place: action, context, plan restriction, sign-in, and free alternative. It is front-loaded, scannable, and contains no filler or redundant restatement 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 simple query-style tool, the description conveys the purpose, the Pro/sign-in constraints, and the relevant sibling alternative. It also hints at lesson context via 'knows the lesson context.' It is less complete on the required level parameter and does not describe possible output, but the overall invocation context is clear enough for an experienced agent.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It implies that 'message' is the question to the tutor and 'lessonSlug' relates to lesson context, a helpful cue. However, it does not clarify the required 'level' parameter, which is not self-evident beyond being a 1-6 number. The description adds almost no explicit parameter-level semantics.

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

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

The description opens with a specific action, 'Ask the Academy Pro AI-Tutor,' and immediately distinguishes it from the sibling academy_tutor_context via 'For free self-tutoring use academy_tutor_context instead.' It also states the Pro plan restriction and server-side lesson context, making the tool's purpose and 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 explicitly says when to use the tool ('Pro plan only,' 'server-side, knows the lesson context') and explicitly tells the agent to use academy_tutor_context instead for free self-tutoring. It also flags authentication requirements with 'Requires sign-in.' This is strong 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?

With only readOnlyHint: true provided by annotations, the description carries the transparency burden, and it does add value by noting the response structure (lesson text, goals, level context) and the 'no Academy account needed' detail. However, it remains silent on edge behaviors like missing slugs, invalid levels, or response size, so it is adequate but not comprehensive.

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 strong front-loading of the core purpose, followed by a compact usage signal. The parenthetical restates the tutor role slightly, but there is no wasted wording and the structure effectively separates 'what it is' from 'when to call it.'

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?

Because there is no output schema, the description correctly bears the burden of describing the return value (lesson text, goals, level context) and does so acceptably. However, given the large sibling list, it fails to position itself against academy_lesson or academy_tutor, leaving ambiguity about when this tutoring-package variant is preferable, making this adequate but incomplete.

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 only 33%, so the description must compensate, yet it leaves 'slug' — a required string with no format hint — completely unexplained, missing the opportunity to point to a sibling list endpoint as its source. It only vaguely gestures at 'level context' and doesn't clarify how level (1-6) affects the result, so it fails to compensate for the coverage gap.

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+resource combination: 'Get a lesson packaged as a tutoring brief: the full lesson text plus its learning goals and the level context,' which clearly states what the tool does. It is differentiated from sibling tools like academy_lesson through the tutoring-brief framing and the 'you are the tutor' role note, though it never names alternatives or explicitly contrasts, so it misses a 5.

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

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

The description contains an explicit usage trigger — 'Call this when the user wants to be *taught* a lesson' — followed by clear role guidance for the agent. It establishes clear context but stops short of 5 because it gives no exclusions or named alternative tools (e.g., when to prefer academy_lesson or academy_tutor instead).

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

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

Annotations already indicate readOnlyHint=true, so the read-only safety is covered. The description adds behavioral context by telling the agent to read the orientation back to the user in their language and offer to start at their level, going beyond the 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?

Two sentences are packed with essential information: when to call, what it returns, curriculum content, and how to use the result. No wasted words; instruction is front-loaded.

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 simple nature, one optional parameter, and read-only annotation, the description fully equips an agent to invoke it appropriately. It covers purpose, content, and user-facing next step.

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 fully describes the single locale parameter with enum values and a default (en). The description only mentions 'in their language,' which adds a minor usage hint but does not substantially augment the schema's 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 specifies a distinct action: always call first when a user connects or asks what this is, and it explains what it returns (orientation for StudioMeyer Academy). This clearly differentiates it from sibling academy_* tools focused on levels, lessons, playbooks, and recipes.

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 trigger condition: 'ALWAYS call this first when a user connects or asks what this is.' This provides direct instruction on when to use the tool, making the guidance unambiguous.

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

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

Annotations already declare readOnlyHint=true, and the description adds that it returns full text of a single item. It doesn't disclose edge cases, error behavior, or additional side effects, but with the annotation baseline this is adequate.

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, clear sentence that states the action, resource, scope, and source of the identifier. Zero unnecessary words.

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

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

For a simple single-parameter fetch tool with read-only annotation MkDocs, the description is sufficient. It states the outcome (full text) and the input source. The lack of an output schema doesn't demand more explanation.

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 describes id as 'Item id from search results'. The description repeats that origin but adds no new meaning 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?

The description clearly states the tool fetches the full text of an Academy item (lesson, playbook, or recipe) by ID. It distinguishes from siblings by covering all three types generically, though it doesn't explicitly contrast with specific item tools like academy_lesson.

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 ID comes from search, giving some usage context. However, it provides no exclusions or guidance on when to prefer this over specific sibling tools like academy_lesson or academy_playbook, leaving the agent to infer the selection.

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

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

The annotation says `readOnlyHint: true`, which is already declared. The description adds that it returns a list of object types and that ids can be passed to `fetch`, which is useful context beyond the annotation. It doesn't disclose any additional behavioral traits like pagination limits or whether it searches metadata only, but the annotation covers the safety profile. No 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 sentences, no fluff. Clearly front-loaded with the purpose, and a second sentence provides actionable follow-up. Minimal and effective.

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 simplicity (1 param, no output schema, readOnly annotation), the description is complete enough. It explains what is returned and how to proceed. It might have been stronger if it clarified whether search is full-text or metadata-only, but that's a minor gap given the context signals. No need to detail return format as there's no output schema.

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

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

With schema coverage at 100%, the description adds little beyond what the schema provides. The description says 'Search query' and the schema says the same. The description does add context that the query will match against content types (lessons, playbooks, recipes), which is slightly helpful. 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?

Description clearly states the tool searches 'StudioMeyer Academy course material' and returns 'a list of matching lessons, playbooks and recipes with ids you can pass to `fetch`'. This is a specific verb+resource with clear scope, and it also connects to the `fetch` sibling, differentiating it from related tools like `academy_search` which might be a Crunchbase search.

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

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

The description does not explicitly say when to use this tool vs alternatives like `academy_search`. However, it implies usage by stating it returns items with ids for `fetch`, serving as a discovery tool. There is no guidance on when not to use it (e.g., for fetching specific items directly). Adequate but not explicit.

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