api

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

The readOnlyHint annotation already indicates this is a safe read operation, and the description adds that it returns a 'linkset for agent discovery', which is mildly informative. However, it does not elaborate on what the linkset contains or whether any network or authentication behavior is relevant, so the description adds limited 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?

The description is a single sentence with no filler, clearly stating the action and object. It is appropriately sized for a zero-parameter tool and front-loads the core message.

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, read-only, straightforward return type), the description is largely complete: it states what is returned and for what purpose. The main gap is not explaining the 'catalog linkset' in more detail or how it relates to sibling discovery tools, but for a simple tool with annotations, the information provided is sufficient.

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. The description naturally does not need to explain parameter meanings, and the empty schema is sufficient.

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 'Return' and identifies the resource as 'Quiz.Video API catalog linkset', making the tool's basic purpose clear. However, it does not explicitly distinguish this from sibling tools like get_llms_txt or get_openapi_spec, which may also serve discovery purposes.

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

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

No guidance is provided on when to use this tool versus alternatives. The phrase 'for agent discovery' implies a use case but does not clarify how this differs from sibling tools like get_llms_txt or get_openapi_spec, nor does it state 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?

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds that the output is 'compact' and 'LLM-readable,' but does not disclose details about the summary's format, length, or content scope, leaving some ambiguity.

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, focused sentence that delivers the core purpose without unnecessary detail or repetition. It is appropriately concise and 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?

For a zero-parameter read-only summary tool, the description conveys the essential function. However, it could briefly note that this is a high-level overview versus structured API specifications, which would help the agent choose appropriately among sibling tools.

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 fully complete. The description correctly avoids parameter information, and with no parameters, no additional semantics are 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 clearly states a specific action: 'Return a compact LLM-readable summary of the Quiz.Video API.' It identifies the resource (Quiz.Video API) and the output format (compact LLM-readable summary), distinguishing it from sibling tools like get_api_catalog and get_openapi_spec.

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 an LLM needs a compact API summary, but it does not explicitly differentiate when to use this tool over get_api_catalog or get_openapi_spec. No exclusions or alternative references 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 description aligns with the readOnlyHint annotation and adds the specific content (the OpenAPI 3.1 spec). It does not disclose additional behavioral traits such as response size, auth requirements, or rate limits, but with a simple read-only tool and no parameters, the bar is lower. The description adds minimal context 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?

The description is a single, direct sentence that conveys the essential information. There is no wasted text 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 tool with no parameters, a readOnly annotation, and a simple output (the OpenAPI spec), the description is complete. It specifies exactly what is returned and does not require additional 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?

The tool has zero parameters, and the schema is empty. The baseline for no parameters is 4, and the description does not need to explain parameter meanings. The schema coverage is 100% (vacuously).

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 action ('Return') and its resource (the Quiz.Video OpenAPI 3.1 specification). It is specific about the format and version, which distinguishes it from sibling tools like get_api_catalog and get_llms_txt.

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 need the OpenAPI specification, call this tool. However, it does not explicitly mention alternatives or when not to use it. The context of sibling tools suggests other documentation endpoints, but no 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 indicate this is a non-readonly, non-destructive operation. The description adds 'Append' to clarify additive behavior without harming existing content. However, it does not disclose potential side effects or requirements (e.g., quiz must exist, correct-answer enforcement), leaving some 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?

A single, concise sentence that front-loads the verb and resource, with no wasted words. Every part contributes to understanding the tool's purpose.

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

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

Given the thorough schema and annotations, the description adequately covers the tool's function. No output schema is present, but the tool is a simple append operation; the description is sufficient for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, with detailed descriptions for quizId and the questions array. The description text adds a high-level summary but does not provide additional meaning beyond what the schema already explains. 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 the specific verb 'Append' with a clear resource ('one or more questions ... to an existing quiz'), distinguishing it from sibling tools like create_quiz or update_quiz. It also mentions the included parts (answers and optional images), fully scoping the action.

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 'existing quiz' provides clear context that this is for modifying an already-created quiz, implying it should not be used for initial creation. It does not explicitly name alternatives or exclusions, but the context is strong enough.

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

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

The description goes beyond annotations by specifying exactly which fields are mutated (template field set to 'custom' and themeCustomization.customTemplate) and clarifying that future edits do not auto-propagate. This is consistent with idempotentHint and readOnly=false.

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

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

Two sentences with no fluff; the first sentence states the action and target, the second provides necessary behavioral detail about the snapshot mechanism.

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, the description covers purpose, fields modified, and the snapshot caveat. It does not explain error cases or return values, but these are not critical for this 2-parameter tool with 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?

Schema description coverage is only 50%, with templateId lacking a description. The description provides context that templateId refers to a custom template and that it's applied as a snapshot, but does not fully clarify the parameter semantics for templateId. It adds some value 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 clearly states it applies a snapshot of a custom template to one or more quizzes, distinguishing it from template creation/update and quiz update tools. It specifies the verb (apply), resource (quiz), and scope (one or more), with context on custom templates.

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

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

It implies usage for applying a custom template to owned quizzes and notes the snapshot behavior. However, it does not explicitly exclude alternatives like manually updating quizzes or re-applying after template changes, so it provides clear context but no explicit when-not conditions.

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 a write operation (readOnlyHint=false, idempotentHint=false). The description's 'Create' is consistent with that but adds no further behavioral context, such as whether a unique deck is always created, what identifier is returned, or if any existing data is affected. No additional constraints or side effects are disclosed, so the description adds little beyond the annotations.

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

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

The description is a single, front-loaded sentence that efficiently summarizes the tool's purpose and core parameter constraints. It has no filler or redundant content, making it appropriately concise for a simple create operation. A slightly richer detail on what the deck is used for would be nice, but not at the expense of 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?

With no output schema, the description should compensate by explaining what the tool returns (e.g., the created deck object or an ID), but it does not. It also omits any mention of how this deck fits into the broader workflow, such as adding quiz questions later or rendering it. The parameter documentation is thorough, but the description lacks essential context for an agent to fully understand the tool's behavior and results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description recaps required/optional parameters and their length constraints, but these are already fully documented in the schema. It adds no deeper semantic insight, such as relationships between cards or the meaning of the 'order' field, which is left to 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 'Create a flashcard deck' uses a specific verb and resource, and the tool name is highly descriptive. It clearly states the action, distinguishing it from other creation tools by the resource type (deck vs. quiz/template). However, it does not explicitly differentiate from siblings beyond the resource name, so minor improvement is possible.

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, no exclusions, and no mention of prerequisites or related workflow steps. It only lists required/optional parameters, which is parameter information rather than usage context. This leaves the agent without insight into the tool's role among the many sibling 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 a write operation (readOnlyHint=false) and non-destructive behavior. The description adds helpful behavioral details beyond that: if themeDescription is omitted the server derives a theme, and backgroundMusicId defaults to YouTube-safe music or null for silent. This is meaningful context, though it doesn't cover return values or duplicate creation behavior.

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 with the core purpose, then gives focused, high-value guidance on theming and music. The final required/optional list is somewhat redundant with the schema but is concise and not padded.

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

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

Given the tool's complexity (12 parameters, nested questions, no output schema), the description summarizes key decision points well: custom theme preference, background music behavior, and required vs optional fields. It is not fully complete because it omits return-value expectations and sibling differentiation, but the rich schema covers parameter details.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description mainly restates required/optional and highlights theme/music defaults, adding limited new semantic value beyond the schema. This matches the baseline of 3.

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

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

The description opens with 'Create a quiz,' clearly stating the action and resource. It is specific but does not explicitly differentiate from sibling tools like quiz_video_generate_quiz, so it misses the top score.

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 parameter-level recommendations ('Prefer sending themeDescription...', 'Omit backgroundMusicId...') and lists required/optional fields, but it gives no guidance on when to use this tool versus alternatives such as generate_quiz or update_quiz.

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 provide readOnlyHint=false, so the agent knows it's a write operation. The description adds minimal behavioral context, only noting that 'hook' is a pass-through object. It does not mention response format, error conditions, or side effects, which would be useful for a create 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 only two sentences, with the core purpose front-loaded. The second sentence adds necessary clarification about the 'hook' parameter without unnecessary detail. Every word serves a purpose.

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

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

The tool has moderate complexity (nested hook object, no output schema, two required params). The description is minimal but adequate, covering the basic operation and pointing to the OpenAPI spec for hook details. However, it omits important operational context such as the return value, behavior if quizId does not exist, or relationship with update/delete hook tools, leaving gaps 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 100%, so the baseline is 3. The description adds meaningful semantic value by explaining that 'hook' is a pass-through object following the HookInput schema, which clarifies that the API likely expects an opaque object and reduces ambiguity about additionalProperties. This goes slightly beyond the schema's own parameter 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 ('Create') and resource ('a hook for a quiz'), which is specific and unambiguous. It distinguishes this from sibling tools like quiz_video_create_quiz and quiz_video_update_quiz_hook by using 'hook' as the object.

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 use when creating a new hook, but it does not explicitly state when not to use it or mention alternatives such as update_quiz_hook for modifying existing hooks. No prerequisites (e.g., quiz existence) or exclusions are mentioned, so guidance is only implied.

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 (readOnly=false), the description discloses the asynchronous nature (polling required, 1-5 minutes), the return of a sessionId, and the immediate availability of the quiz. This added context is valuable and does not contradict annotations, providing a complete picture of expected behavior.

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, each earning its place: action, workflow, and an important caveat. It is front-loaded with the core purpose and contains no filler or redundant details.

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

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

Given only one parameter and no output schema, the description covers the essential workflow (queue, poll, download) and notes immediate quiz availability. Missing are potential failure modes, but the description is thorough for a simple async rendering 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 coverage is 100%, so the baseline is 3. The description adds minimal extra meaning about quizId beyond the schema (e.g., 'existing quiz'), but it does not elaborate on format or edge cases. The schema already describes the parameter adequately.

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 with a specific verb and resource: 'Queue a new video render for an existing quiz.' It distinguishes itself from sibling tools by naming the subsequent workflow (poll get_render, download_render), making the purpose 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?

Explicit usage guidance is provided: it instructs to poll quiz_video_get_render until status is 'completed' and then call quiz_video_download_render. It also notes that the quiz is viewable immediately, clarifying when this tool is necessary. This effectively guides the agent through the full workflow and 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 indicate this is a mutating, non-idempotent, non-destructive operation. The description adds that it saves a template from the editor, but does not disclose return behavior, validation requirements, or side effects like the isDefault replacement behavior (which is only in the schema). 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: the first clearly states the action, the second enumerates required and optional parameters. Every word adds value, and it is front-loaded with the primary purpose.

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

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

For a tool with 6 parameters, a nested object, and no output schema, the description is functional but incomplete. It does not mention what the tool returns, how validation fails, or the implications of isDefault/isPublic. It provides a basic overview but leaves gaps for an agent to infer.

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 67% (4 out of 6 params have descriptions), and the description adds a brief summary of required vs. optional parameters without introducing new meaning beyond the schema. It highlights 'template' as required and lists the optional fields, which is helpful but not a significant addition.

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 with a specific verb ('Save a new') and resource ('custom template'), and adds the context of being authored in the drag-and-drop editor. This clearly distinguishes it from sibling tools like apply_template and update_template by emphasizing 'new.'

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: use this tool when you have authored a new custom template in the editor. It does not explicitly name alternatives or when-not-to-use scenarios, but the 'new' wording implicitly contrasts with update/apply operations. This is sufficient context for an agent to select it appropriately.

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 behavioral context beyond the annotations by noting permanence ('permanently delete') and cascading deletion ('all of its cards'). While annotations already declare destructiveHint=true, this extra detail clarifies irreversible scope. 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 a single, concise sentence that front-loads the key action and resource. It includes no filler or redundant information, earning every word.

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 low complexity (one parameter, no output schema) and strong annotations (destructive, idempotent, read-only false), the description is complete. It conveys the essential behavior and resource scope without needing to explain return values or error cases.

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% as the single parameter 'deckId' has a description ('Flashcard deck ID.'). The tool description does not add additional meaning about the parameter, 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 action ('delete') and the resource ('flashcard deck') with additional scope ('all of its cards'), which distinguishes it from sibling tools like quiz_video_get_flashcard_deck, quiz_video_update_flashcard_deck, and quiz_video_create_flashcard_deck. 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?

The description implies the tool is used when the user wants to permanently remove a flashcard deck, but it does not explicitly state when not to use it or mention alternatives. There are no exclusionary conditions or alternative tool references, 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 destructiveHint: true and idempotentHint: true, but the description adds value by specifying 'permanently delete' and enumerating exactly what gets destroyed, going beyond the generic annotation. No contradiction is present.

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 immediately states the action and its consequences. It contains no superfluous 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 delete operation with one parameter, the description fully explains the tool's effect, and the annotations cover the idempotent and destructive nature. The absence of an output schema is acceptable here as the outcome is already clearly 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 fully documents the single parameter 'quizId' with a description of its format. The tool description adds no additional parameter meaning, so it does not exceed the baseline provided by the complete schema coverage.

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

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

The description clearly states the tool permanently deletes a quiz, and specifically enumerates the cascading deletion of questions, answers, and hooks. This distinguishes it from sibling tools like delete_quiz_hook, making the purpose 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 provides clear context by indicating the scope of deletion (quiz plus associated questions, answers, hooks), which implicitly guides when to use this tool versus more targeted delete tools. However, it does not explicitly state exclusions or alternative scenarios.

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=true and readOnly=false, so the description adds no additional behavioral context beyond what is already structured. It does not disclose permanence, side effects, or any specifics beyond the basic delete 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 sentence, front-loaded, with no fluff or redundant words. It is appropriately sized for the tool's simplicity.

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, full parameter schema, and annotations that cover safety, the description is sufficient. It lacks any mention of return value or deletion scope, but these are not critical given the context.

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 100% coverage with descriptions for both quizId and hookId, so the schema already documents the parameters. The description adds no extra meaning beyond restating that the target is a single hook from a quiz.

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 'Delete a single hook from a quiz' uses a specific verb and resource, clearly distinguishing it from sibling tools like create, update, or list. The title and description are aligned 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?

The usage is implied by the action: it is used when the intent is to remove a hook. However, there is no explicit guidance on when to prefer this over create/update/list, or any mention of prerequisites or restrictions.

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

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

Beyond the destructiveHint annotation, it specifies that deletion is permanent, applies only to templates you own, and explicitly states that existing quiz snapshots remain in their themeCustomization. This adds real behavioral context about what is destroyed and what is preserved.

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 resource, followed by a single clarifying consequence. No wasted words, and the structure balances directness with necessary 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 delete operation with one parameter and no output schema, the description covers permanence, ownership, and the non-obvious behavior regarding quiz snapshots. Annotations provide idempotency and destructive hints, making this fully adequate for an agent to select and 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?

The single parameter templateId is self-explanatory from the schema and tool name, and the description adds the ownership requirement that gives context for the ID. However, schema coverage is 0%, so the description carries the burden and could have explicitly stated that templateId must refer to an owned template, though it already implies 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 a specific verb ('Permanently delete') and resource ('a custom template you own'), distinguishing it from sibling deletion tools like delete_quiz and delete_flashcard_deck. The ownership qualifier adds precision beyond the title.

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 (delete a template you own) and clarifies a key effect (snapshots in quizzes are unaffected), which informs whether the operation is safe. However, it does not explicitly contrast with alternatives like update_template or mention when not to use it, such as if a template is actively referenced.

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 context beyond the annotations by mentioning 'signed' (implying authentication/expiration) and 'completed render' (a precondition). Annotations already provide destructiveHint=false and idempotentHint=true, so the safety profile is covered. The additional context about signing is valuable but not exhaustive.

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 of 10 words, directly states the action and object, and contains no filler. Every word earns its place, making it extremely efficient and 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?

The tool is simple (one parameter, no output schema) and the description covers the essential purpose and precondition. Annotations handle idempotency and destructiveness. It could be more complete by noting potential errors (e.g., render not completed) or URL expiry, but for its simplicity, it is adequately 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 sessionId described as 'Render session id for a completed render.' The tool description reiterates the completed-render condition but does not add new parameter details (e.g., format, constraints, or behavior). Baseline 3 is appropriate because the schema carries the full 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 clearly states the action (request), the resource (signed download URL), and the target (completed render). This distinguishes it from sibling tools like get_render (which retrieves render status) and create_render (which initiates rendering), making the purpose unmistakable.

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

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

The description provides clear context: use this tool when you need a signed URL for a render that is already completed. It implies the precondition that the render must be done, but it does not explicitly name alternatives or state when not to use it, which keeps it from 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?

Beyond the annotations (which simply indicate a non-read-only, non-idempotent operation), the description discloses important side effects: it saves a quiz, may derive and save a custom theme when omitted, and when autoRender is true returns a queued render session to poll. It also states that the response always includes a watchUrl. This is useful behavioral context beyond what the structured annotations provide, though it could be more explicit about the default render-queue behavior when autoRender is false.

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

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

The description is four sentences, each conveying distinct, high-value information: the core action, theme recommendation, music default, and response/render details. It is front-loaded with the most important information and contains 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 tool with 15 parameters, a nested object, and no output schema, the description does a good job explaining the essential response characteristics (watchUrl always present, data.render when autoRender is true). It could also briefly describe the general quiz object shape or mention that a quiz is returned directly even without autoRender, but the combination of high schema coverage and the description's key response notes makes it reasonably 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?

With 100% schema description coverage, the baseline is 3, but the description adds meaningful guidance: it recommends preferring themeDescription/themeCustomization and explains the fallback behavior when they are omitted ('the server derives and saves a topic-based custom theme'). It also clarifies the default vs null behavior for backgroundMusicId. These insights go beyond the parameter schemas and help the agent choose correct 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 clearly states the tool's specific action: 'AI-generate and save a quiz from a topic.' The verb 'generate' (with AI) distinguishes it from the sibling tool 'quiz_video_create_quiz' (which likely implies manual creation), and it also specifies the input (topic) and output (saved quiz). This is a clear, purpose-specific verb+resource combination.

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 practical guidance on parameter selection: 'Prefer providing themeDescription or themeCustomization' and explains the default music behavior ('Omit backgroundMusicId to use default... set null for silent'). It also explains how to follow up on autoRender ('poll quiz_video_get_render'). However, it does not explicitly mention when to use this tool over sibling tools like quiz_video_create_quiz or quiz_video_create_render, so it falls short of an explicit alternative/exclusion list.

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 indicates a safe read operation. The description adds the behavioral detail that it requires authentication ('authenticated user') and specifies what is returned (account info, plan, usage limits), providing useful context 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?

The description is a single, well-structured sentence with no fluff. It front-loads the verb 'Get' and provides just enough detail to convey the tool's purpose.

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

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

For a no-parameter, read-only tool with a readOnlyHint, the description is sufficient. It fully explains the return categories and the fact that it targets the authenticated user's account, covering the tool's complete behavior.

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 there is no parameter ambiguity. The description provides meaningful context about the output, and baseline 4 is appropriate for 0-parameter tools.

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 'Get' and clearly identifies the resource as 'the authenticated user's account info, plan, and usage limits.' It distinguishes the tool from sibling tools that target other resources like quizzes, templates, and renders.

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 implies this is the tool for retrieving account-level data, and no sibling tool targets account info. However, it does not explicitly state when to use or not use it, so it lacks direct exclusion guidance.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds that the deck includes all cards, which is helpful, but it does not cover error behavior, return format, or how a missing deck is handled. Minimal behavioral detail 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?

One sentence, front-loaded, with no fluff. Perfectly 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?

For a simple one-parameter read-only fetch with good annotations, the description is sufficient. It tells the agent the key fact (all cards are included) and the required id. No output schema exists, but the description doesn't need to explain return values extensively for such a straightforward 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 fully describes the single parameter deckId as 'Flashcard deck ID', and the description's 'by id' aligns with this. The description adds no additional semantics 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 the action ('Fetch'), the resource ('flashcard deck'), and the scope ('by id'), and explicitly mentions it includes all cards. This differentiates it from sibling tools like quiz_video_list_flashcard_decks (which lists decks) and create/delete variants.

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 you have a deck ID and need the full deck contents, but it does not explicitly contrast with alternatives such as quiz_video_list_flashcard_decks or other get tools. The 'by id' qualifier gives some context, but no when-not-to-use guidance 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?

The annotation readOnlyHint=true already declares the read-only safety profile, so the description does not need to restate it. It adds behavioral context by noting that settings and metadata are included, but it does not describe the exact return structure or error handling, which leaves some 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 11-word sentence, front-loaded with the verb and object, and contains no redundant or tangential 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 get-by-id tool with one fully documented parameter and a readOnly annotation, the description provides adequate context. It specifies the scope and what is included, though the lack of an output schema means return format is only lightly characterized.

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 quizId, including its YouTube-style base64url format. The description's 'by id' adds nothing beyond what the parameter name and description already convey, so the baseline score 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 the specific verb 'Fetch' and identifies the resource as 'a single quiz... by id', clearly distinguishing it from sibling tools like quiz_video_list_quizzes or quiz_video_create_quiz. It is concise 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?

The context is clear: use this tool when you have a quiz ID and need a single quiz's settings and metadata. It does not explicitly name alternatives, but the emphasis on 'single' and 'by id' implies the contrast with listing or creating tools.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable context beyond annotations: it reveals what the response includes in the completed state (signed videoUrl and filename) and what in-progress polls return (status + progress). This helps the agent understand the tool's behavior without needing an output 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 only two sentences and front-loads the primary purpose in the first sentence. The second sentence adds essential edge-case behavior (completed vs. in-progress) without redundancy. 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 polling tool with no output schema, the description is complete. It explains both possible responses (completed with videoUrl, in-progress with status+progress) and even references the download alternative. There is no missing information an agent would need 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 coverage is 100% for the single sessionId parameter, and the description does not add further param details. The schema already documents that sessionId is the render session id returned when the render was started. Baseline 3 is appropriate given high schema coverage and no need for extra compensation.

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: 'Fetch the status and progress of a render session.' It also distinguishes itself from the sibling quiz_video_download_render by explaining that a completed render includes a signed videoUrl, so no separate download call is needed. This clearly identifies the tool's unique role.

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

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

The description explicitly states when to use this tool versus the download alternative: when status is 'completed', the response contains a direct videoUrl, avoiding a separate quiz_video_download_render call. It also characterizes polling behavior ('In-progress polls return status + progress'), giving the agent clear context for repeated checks.

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 the annotation readOnlyHint=true already signaling a safe read, the description adds value by disclosing that the response includes the full scenes/layers payload. This gives the agent useful expectations about the returned data beyond what the annotation provides.

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, highly efficient sentence that front-loads the action and object ('Fetch a single custom template') and adds the key return detail ('including the full scenes/layers payload'). 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 single-parameter retrieval tool with readOnlyHint=true and no output schema, the description is complete. It explains what the tool does, what parameter it needs, and what the response will contain, leaving no critical gaps.

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

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

The input schema has full parameter coverage: templateId is described as 'Template id (tpl_...).' The description does not add much beyond restating 'by id', but since the schema already handles the parameter meaning, 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 a specific verb ('Fetch') and resource ('single custom template') with a precise scope ('by id'). This distinguishes it from sibling tools like quiz_video_list_templates, which presumably fetch multiple templates without an id.

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 tool is for retrieving one specific template when you have its ID, providing clear context. It does not explicitly mention alternatives or exclusions, but the 'by id' phrasing makes the usage scenario 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, so the safety profile is established. The description adds the ownership scope and pagination behavior, but doesn't disclose return format, ordering, or any rate limits. 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?

A single, concise sentence that directly states the core functionality and scope. Every word earns its place; 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?

For a simple list operation with no output schema, the description covers purpose, ownership scope, and pagination. The input schema fully documents parameters, and annotations declare the safety profile. No critical gaps remain.

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%: both page and limit have descriptions. The description mentions 'optional pagination' but adds no new details beyond the schema. Baseline of 3 applies since 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 clearly states a specific action ('List') on a specific resource ('flashcard decks'), scoped to the authenticated user, with optional pagination. This distinguishes it from sibling list tools like quiz_video_list_quizzes or quiz_video_list_templates.

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 needing to list the user's own flashcard decks. It provides clear context (ownership, pagination) but doesn't explicitly mention alternatives or exclusions. The distinction from siblings is implicit via the resource type.

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 tells the agent this is a safe read operation. The description adds the scope ('background music tracks') but does not disclose what fields are returned (e.g., track IDs, names, URLs). Given the annotation covers the safety profile, a neutral score 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?

The description is a single, focused sentence with no filler or redundancy. It is perfectly front-loaded and compact.

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 list operation with no parameters and a readOnly annotation, the description fully captures the tool's behavior. No output schema exists, but the described return value (list of tracks) is implicit and sufficient for this low-complexity 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, so the baseline is 4. The description does not need to explain parameters that do not exist.

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 'List available background music tracks' uses a specific verb ('List') and a specific resource ('background music tracks'), making the function unambiguous. It clearly distinguishes itself from all sibling tools, none of which deal with music.

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: use this tool when you need to see available background music tracks. It does not explicitly state when not to use it or mention any alternatives, but given that it is the only music-listing tool and the operation is trivial, the implied context is adequate.

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

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

The description is consistent with the readOnlyHint annotation and adds minimal context beyond it, specifying the scope 'configured for a quiz.' It does not disclose pagination, ordering, return format, or edge-case behavior. Since annotations already cover the read-only nature, the description adds limited behavioral insight.

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 immediately conveys the action and resource. It is appropriately concise with no 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 read-only list tool with one documented parameter and a readOnlyHint annotation, the description is mostly adequate. However, without an output schema, it does not describe the response structure, which could leave the agent uncertain about what is returned. Given the tool's simplicity, the description is nearly complete but lacks explicit mention of the return list 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?

The tool description does not add information about the quizId parameter beyond the schema, which already provides a detailed description (YouTube-style 11-character base64url). Schema description coverage is 100%, 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 the specific verb 'List' and identifies the resource as 'video hooks configured for a quiz,' clearly distinguishing it from sibling tools for creating, updating, or deleting hooks and from listing other resources like quizzes or questions.

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 for viewing hooks of a specific quiz, but provides no explicit guidance on when to use this tool versus alternatives such as creating, updating, or deleting hooks. No exclusions or alternative tools are mentioned.

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 is consistent with a read-only operation. It adds the detail that answers are included but does not discuss pagination, ordering, or response format. Since annotations already cover the safety profile, the minimal extra context yields a baseline score.

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 communicates the essential function with no wasted words. It is well-structured and 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?

For a simple read-only list operation with one well-documented parameter and no output schema, the description sets adequate expectations. It could optionally mention whether the list is ordered or complete, but such details are not critical for this straightforward 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 provides 100% coverage for the single parameter, including a clear format description ('YouTube-style 11-character base64url format'). The tool description adds no additional parameter semantics beyond what the schema already states, 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 'List questions (and their answers) for a quiz' – a specific verb ('list') with a specific resource ('questions for a quiz'). It distinguishes itself from sibling tools like quiz_video_list_quizzes by focusing on questions within a specific quiz.

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 case (enumerating questions for a given quiz) but does not explicitly state when to use it over alternatives like quiz_video_get_quiz or quiz_video_list_quizzes. No exclusions or alternative tool names 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 readOnlyHint annotation already indicates a safe read operation. The description adds important behavioral detail: the list is scoped to the authenticated user's ownership, and pagination is optional. These details go 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?

The description is a single, well-structured sentence that conveys scope, ownership, and pagination in a front-loaded manner. Every element is purposeful with no filler or repetition.

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

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

For a simple list tool with only two optional parameters fully described in the schema, the description is largely complete. It covers the resource, scope, and pagination. The lack of an output schema is a minor gap; the description doesn't explain return values, but this is acceptable for a straightforward list endpoint.

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 already fully documents both parameters (page and limit) with types, ranges, and defaults, achieving 100% coverage. The description only names the parameters and marks pagination as optional, adding minimal semantic value beyond the schema. 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 uses a specific verb 'List' with the resource 'quizzes' and adds a crucial differentiator: 'owned by the authenticated user'. It also mentions optional pagination, which clarifies the operation's scope and distinguishes it from sibling list tools. This is clear and specific.

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 implies usage context: to list quizzes owned by the current user. While it doesn't explicitly name alternatives, the ownership scope and resource type make it obvious when to use this tool versus other list tools (e.g., list_quiz_questions). No exclusions, but the 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 declare readOnlyHint=true, and the description adds behavioral context by specifying that it returns the caller's own templates unless public ones are included. This goes beyond the annotation and clarifies the scope of the listing.

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 action, and every sentence adds value. No extraneous 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 list tool with read-only annotation and no output schema, the description sufficiently explains what it lists and what templates are. Missing details about output format or pagination are not critical, but could be more 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?

Schema description coverage is only 33%, with only includePublic described. The description mentions 'optionally public ones' which aligns with includePublic, but does not add meaning for page or limit parameters. The description fails to compensate for the low schema coverage.

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

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

The description clearly states the tool lists the caller's saved custom templates, with an optional inclusion of public ones. It uses a specific verb (list) and resource (custom templates), and distinguishes from sibling tools like get_template, update_template, and apply_template.

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 context by explaining what templates are, but does not explicitly state when to use this tool versus alternatives like get_template or apply_template. Usage is implied but not clearly guided.

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=false, idempotent=true, destructive=false, so the agent knows this is a safe-to-repeat write operation. The description adds the partial-update behavior ('any subset') which is not in annotations, but doesn't disclose anything about return values or external side effects (openWorldHint).

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 action ('Update a quiz') and immediately explains the key semantics of the updates parameter. 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?

Given the large nested schema and comprehensive annotations, the description is sufficient for an agent to understand the tool's role. It lacks details about return values, but no output schema is expected, and the schema's thorough field descriptions compensate. A brief note about applying themeCustomization automatically would be helpful but not essential.

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% coverage with detailed descriptions for every field, so the baseline is 3. The description adds a high-level summary of updateable settings and the 'any subset' behavior, but this information is also present in the schema's updates field description ('Partial quiz settings object; only included fields are updated').

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 'Update a quiz' with a clear verb and resource, and lists the categories of settings ('title, description, format, template, timing, music, TTS, publish status, etc.'). This clearly distinguishes it from sibling create/delete/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 clearly implies partial updates ('accepts any subset of quiz settings'), giving context on when to use this tool for modifying existing quizzes. It does not explicitly name alternatives like quiz_video_create_quiz or quiz_video_delete_quiz, but the update context is unambiguous given the tool name and siblings.

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

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

Annotations already indicate mutating (readOnlyHint=false), non-destructive (destructiveHint=false), idempotent, and open-world behavior. The description adds useful context that updates are partial (only included fields are changed) and that hookId must be numeric, which is not fully captured by 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 a single concise sentence that immediately communicates the action, resource, and core requirements. Every word earns its place with 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 tool with three well-documented parameters and no output schema, the description covers the essential behavioral aspects: what it does, required identifiers, and partial-update semantics. It lacks explicit return-value/error details, but those are not required given the simplicity and existing 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 coverage is 100%, with each parameter described in the schema. The description repeats the numeric hookId constraint and 'partial HookInput' semantics already present in the schema. It adds no new parameter-level meaning beyond the schema, hence baseline 3.

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

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

The description 'Update an existing hook on a quiz' clearly states a specific action (update) on a specific resource (hook on a quiz), distinguishing it from siblings like create_quiz_hook, delete_quiz_hook, and list_quiz_hooks. It also adds necessary identification requirements.

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 stating prerequisites ('Requires quizId and numeric hookId; updates is a partial HookInput') but does not explicitly mention when to use this tool versus create or delete alternatives. No exclusions or alternative tool references 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?

The description discloses that omitted fields stay unchanged, which is a key behavioral trait beyond the annotations. Annotations already cover idempotency and non-destructiveness, so the description adds useful context without contradicting them.

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

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

The description is two concise sentences, front-loaded with the primary action and then adding the key partial-update behavior. Every word earns its place with 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 an update tool with 7 parameters and no output schema, the description captures the essential behavior (partial update) but omits details like error handling for invalid templateId or the nature of the nested 'template' object. Overall, it is sufficient for basic use but not exhaustive.

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 burden. The statement 'any subset of fields may be supplied' provides general optionality, but it does not explain individual parameters, especially the nested 'template' object. This is adequate but not rich.

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 action with a specific verb ('Update') and resource ('an existing template'), distinguishing it from sibling tools like create/delete/get template. The additional partial-update semantics further clarify its specific role.

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

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

The description provides clear context for when to use the tool (updating an existing template) and indicates that any subset of fields can be supplied. It does not explicitly mention alternatives or exclusions, but the purpose is self-evident within the sibling family.

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