QuizLink

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: the call is FREE (no coin cost, which matters given sibling tools that likely consume coins) and it enumerates the guide's content scope. It stops short of describing the returned guide's shape, but that is a minor omission for a read-only informational 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?

Front-loaded with the purpose before the usage constraints and content summary, so the most important sentence comes first. It is slightly padded by four near-synonymous example phrasings and a redundant negative list, but the exclusions do guard against over-triggering.

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?

No output schema exists, and the description compensates by listing what the guide displays (coin costs, input sources, 8 learning types, study games). With annotations covering safety and the single optional param documented in schema, the only gap is that resuming onboarding via user_id is never mentioned.

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?

Only one optional parameter and schema description coverage is 100%, so the schema already documents user_id as an 'Optional user ID to resume existing onboarding.' The description says nothing about it and adds no meaning — the baseline 3 applies when the schema does all the work.

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

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

States a specific verb and resource — 'Show QuizLink's interactive feature guide' — and immediately scopes it to user questions about QuizLink itself. No sibling tool serves this purpose, and the description makes that distinction explicit rather than relying on the name.

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

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

Gives both positive triggers with concrete example phrasings ('what is QuizLink?', 'show me QuizLink features') and an explicit exclusion list covering general questions, math, and conversation. An agent can decide whether to call this tool without any inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is structured. The description adds genuinely new operational context: authentication required and that the call is free and does not count against rate limits — information not available anywhere else. Only gap is not saying what happens when the course is already bookmarked or what the response contains.

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

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

Four short sentences, each front-loading the most important fact (what it does, then auth, then cost, then idempotency). Minor waste: the idempotency sentence largely restates idempotentHint=true, though it adds the 'same course_id' clarification.

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

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

For a one-parameter, non-destructive bookmark tool with annotations covering safety and no output schema, the definition supplies the key operational facts (auth, free/rate-limit-free, idempotent). It is nearly complete; only the course_id provenance and already-bookmarked behavior are missing.

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

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

Schema description coverage is 0% and the single required parameter course_id has no documented format, source, or example. The name is fairly self-explanatory, but the description does nothing to compensate — it never mentions where to obtain a valid course_id (e.g., from my_courses).

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

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

States a specific verb and resource ('Add a course to your favorites/bookmarks') plus the resulting state ('quick access later'). The add/remove contrast with the sibling remove_liked_course is implicit in the verb but the sibling is never named, so it stops short of a 5.

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

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

'for quick access later' implies the use case, and 'Requires authentication' is a useful precondition. However, there is no explicit when-not guidance (e.g., don't call if already bookmarked, use remove_liked_course to undo) and no alternatives are named.

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 destructiveHint=true and idempotentHint=true, and the description adds real context beyond that: authentication requirement, no coin cost, the reset_to_default escape hatch, and the full defaults list so the agent knows what "default" means. It stops short of stating whether partial updates overwrite or preserve untouched fields, which is the key remaining behavioral question for a destructive, all-optional update.

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

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

Front-loaded with the core action plus auth/reset notes, then a scannable Settings block with one line per parameter and a compact Defaults line. It is on the long side, but nearly every line is actionable reference material rather than 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 seven-parameter, all-optional mutation tool with no output schema, the description covers auth, cost, per-field formats, defaults, and the reset path -- enough to call it correctly. The missing piece is the merge-vs-replace semantics for omitted fields, which matters given destructiveHint=true.

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

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

Schema description coverage is 0%, so the description must carry all seven parameters, and it does: language, card_styles, image_theme, image_source, reset_to_default, and the cards_per_unit_min/max range are each explained with formats and examples. The gap is null semantics -- nothing says whether passing null leaves a setting unchanged or clears it.

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

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

States a specific verb and resource ("Update your flashcard generation preferences") that clearly differs from the read-only sibling my_flashcard_settings and the content-editing sibling edit_flashcards. It never names those siblings explicitly, so an agent must infer the distinction, but the purpose itself is unambiguous.

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

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

Usage is implied by the wording and reinforced with concrete instructions ("Set reset_to_default=true to restore all defaults"), and the authentication/free-cost notes help an agent decide it is safe to call. However, there is no explicit when-to-use/when-not guidance relative to my_flashcard_settings or edit_flashcards, nor any warning about whether omitted fields are preserved.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true. The description adds meaningful context such as authentication and 'FREE (no coin cost),' but does not explain what the destructive behavior means, whether omitted fields remain unchanged, or how existing podcast generation settings are affected.

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

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

The description is front-loaded with the core action and then organized into settings and examples. The examples are valuable for a six-parameter tool, though the overall text is somewhat longer than strictly necessary.

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 six-parameter settings tool with no output schema, the description covers invocation well and documents every parameter. Its main gap is behavioral: with destructiveHint=true, it should clarify what is overwritten or irreversible rather than only listing accepted values.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it documents all six parameters with allowed values, constraints, and examples. This goes well beyond the bare schema types.

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

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

The description states a specific verb and resource: 'Update your podcast generation preferences.' This clearly distinguishes it from create_podcast and edit_podcast, though it does not explicitly name sibling alternatives such as my_podcast_settings.

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 useful invocation context: authentication is required, all fields are optional, and examples show how to perform common updates. However, it does not explicitly say when to use this tool versus my_podcast_settings or change_quiz_settings, nor does it provide exclusions.

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

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

Annotations already declare non-read-only, destructive, and idempotent behavior. The description adds meaningful context beyond annotations: authentication is required, all fields are optional with partial-update semantics, and the operation is free with no coin cost.

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 no wasted sentences. It moves efficiently from purpose to authentication, customizable fields, update semantics, and cost.

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 output schema and full annotation coverage, the description is largely complete: it covers authentication, partial updates, field meanings, and cost. It still leaves some parameter semantics ambiguous, especially min/max question bounds and allowed enum-like values.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It enumerates the fields and gives useful constraints for passing score and questions per unit, but it does not clearly distinguish questions_per_unit_min from questions_per_unit_max or define valid difficulty and language values.

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 and resource: update quiz generation preferences. It is distinguishable from most siblings, though it does not explicitly contrast with my_quiz_settings or create_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?

Usage is implied by 'Update your quiz generation preferences,' and authentication is noted, but there is no explicit guidance on when to use this versus viewing settings with my_quiz_settings or creating a quiz with create_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 declare it is a non-read-only, non-destructive, idempotent, closed-world mutation; the description adds real value beyond that by naming the side effects (XP award, next-unit unlock, course-completion check) and the cost profile ('FREE call - no coin cost'). It stops short of saying what happens when score < 50 (error vs. no-op) or what the call returns, which matters for a mutation with no 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?

Four short sentences, front-loaded with purpose, then trigger, then cost. Every sentence carries information the agent cannot get from the schema or annotations; there is no filler.

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

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

For a 4-parameter, 3-required mutation with no output schema, the description covers purpose, trigger, precondition, side effects, and cost. The remaining hole is outcome behavior on a failing score and the shape of the response (XP granted, next unit id, course-complete flag), which the agent cannot 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 100%, so the baseline here is 3; the description still earns a bump by reinforcing the gating rule (≥50 passing score) and by contextualizing learning_type through the 'learning widgets (quiz, flashcards, etc.)' list. It adds nothing about the unit_id/course_id pairing (e.g., whether the unit must belong to that course).

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

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

States a specific verb and resource ('Mark a learning unit as completed') plus the exact effect set (awards XP, unlocks the next unit, checks course completion). No sibling tool in the list performs unit completion, so an agent can disambiguate it from the create_*/edit_* family without opening any schema.

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

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

Gives a clear trigger and provenance: 'Called automatically by learning widgets (quiz, flashcards, etc.) when the user finishes,' and states the ≥50% precondition. It does not explicitly say whether an agent should ever call it directly or what to do instead when the score is below threshold, so no exclusion/alternative routing is provided.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that generation is AI-driven and produces word-clue pairs plus an interactive grid, which hints at latency/cost, but it never states that generation is slow, may consume credits, or whether the puzzle is persisted or merely returned. Since 'creates' plus openWorldHint implies external processing, a 3 is appropriate — useful context, not rich disclosure.

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

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

Three sentences, each doing distinct work: what it generates, the mode split with parameter grouping, and the mode summary. The generative action is front-loaded with no preamble 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 complex, open-world generative tool with 13 parameters and no output schema, the description covers inputs well and sketches the return ('word-clue pairs and an interactive grid puzzle'), but says nothing about generation time, failure modes for invalid URLs, or whether results persist server-side. An agent can call it, but cannot predict cost or post-call state.

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 baseline is 3, but the description adds genuine structural meaning: it groups the 13 parameters into two mutually exclusive modes and enumerates the exact source set (notes/webpage/youtube/documents/images/audio/ai_research/ai_chat_context) that belongs to the standalone mode. That mutual-exclusivity framing is the single most important thing an agent needs and is only weakly implied by the schema's '(optional - use this OR provide sources)'.

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

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

States a specific verb and resource ('Generate an AI-powered crossword puzzle') and immediately splits it into two named input modes (unit_id vs. custom sources). The resource is distinct enough from siblings like create_quiz, create_flashcards, and create_mcq that an agent can pick it without opening the schema.

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

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

The 'either unit_id or custom sources' framing is real routing guidance, reinforced by 'Supports both course-based and standalone modes', which resolves the otherwise ambiguous 13-param, zero-required schema. It stops short of naming alternatives or exclusions — e.g. that edit_crossword should be used to modify an existing puzzle rather than creating a new one.

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 genuinely useful context beyond annotations: a fixed 5-stage progressive output with an animated reveal, and a 15-coin cost. Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so this is solid but not exceptional; it does not say whether the diagram is persisted, returned as images, or editable afterward.

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

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

Four short sentences, front-loaded with the core action, then output shape, then cost. Each sentence carries information; only the 'and more' trailing clause is filler.

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

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

With only two parameters and annotations present, most of the burden is light, but there is no output schema and the description never says what the caller receives (image URLs, a diagram ID for edit_excalidraw, a session link). That missing hand-off detail is the one real gap for an agent that may need to edit afterward.

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

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

Schema description coverage is 100%, with both prompt and ai_chat_context documented in-schema, so the baseline is 3. The description mentions 'any concept' and diagram categories but adds nothing about how to shape the prompt or when ai_chat_context matters.

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

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

States a specific verb and resource ('Create a hand-drawn style diagram using Excalidraw') and enumerates concrete artifact types (flowcharts, mind maps, math visualizations, system architectures). The 'hand-drawn style' qualifier and the Excalidraw name separate it cleanly from create_infographic and the other create_* siblings.

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

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

There is no guidance on when to pick this over create_infographic, study_concept, or edit_excalidraw. 'For any concept' is the opposite of a selection criterion, and no prerequisites or exclusions are given.

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

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

Annotations already declare this is a non-read-only, open-world, non-destructive operation. The description adds useful behavioral context: it generates exactly 5 questions and includes multiple alternative answers per question. However, it does not explain persistence (where the quiz is stored), whether course_id affects unit completion tracking, or what the response looks like, leaving meaningful behavioral gaps for a creation 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 three sentences, front-loaded with the core capability, then mode distinctions, then output detail. Every sentence contributes useful information without redundancy, despite the long source list being schema-redundant.

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

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

For a complex, 13-parameter creation tool with no output schema, the description covers the main modes and question structure. However, it omits important context such as where generated quizzes are saved, whether the tool returns quiz IDs or question objects, and how course_id tracking interacts with generation. The rich schema mitigates this, but some agent-critical context is still missing.

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

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

Schema coverage is 100%, so parameter-level details are already handled by the schema. The description still adds value by grouping parameters into two mutually exclusive modes (unit_id vs. title plus sources) and clarifying that title is required for standalone generation. This mode grouping helps an agent navigate the 13 optional parameters beyond individual 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 states a specific verb and resource: 'Generate 5 AI-powered fill-in-the-blank questions.' It also distinguishes the two creation pathways (unit_id vs. custom sources) and notes that each question has alternative answers, which separates it from sibling tools like create_mcq or create_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 clearly explains the two usage modes: course-based via unit_id and standalone via title plus sources. It does not explicitly compare itself to sibling creation tools (e.g., create_mcq, create_quiz) or state when not to use it, but the mode-selection guidance is strong and actionable.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the mutation/open-world profile is known; the description usefully adds the fixed output shape (5 cards, question/answer/hint, AI images). It omits what side effects occur on the user's course/unit and whether generation is idempotent or replaces existing 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?

Front-loaded with the outcome, which is good, but it spends two sentences restating the same point ('comprehensive research → better flashcards') and embeds a verbose inline JSON example. Roughly a third of the text is redundant.

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

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

For a 13-parameter generation tool with no output schema and open-world behavior, the description covers the happy path but leaves the source-selection logic (unit_id OR sources, auto_research defaults) to the schema and says nothing about returned artifacts. Adequate but with clear gaps.

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

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

Schema coverage is 100%, so the baseline is 3; the description reiterates title, ai_research, notes, webpage_url and youtube_link. It adds no semantics for unit_id, course_id, auto_research, or the image/audio/document URL arrays, and it asserts 'title (required)' while the schema marks zero required parameters — a mild conflict that does not help the agent.

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

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

States a specific verb and resource ('Generate 5 flashcards with illustrations and interactive quizzing'), which tells an agent exactly what will be produced, including card granularity. It does not differentiate itself from edit_flashcards or create_quiz, but the create-vs-edit distinction is inferable from the name alone.

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

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

Gives a 'to use' recipe (provide title + ai_research) and says sources are optional, which is usable invocation guidance. However it never says when to pick this over edit_flashcards or another content generator, nor what the prerequisites (existing unit/course) are.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the agent knows this is an external, non-destructive write. The description adds generation-specific behavior (AI-authored content, 17 layouts, 12 styles, dual mode) but says nothing about latency, cost, whether the artifact is persisted, or how the result is returned — notable for an AI generation call with no 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?

Three sentences, front-loaded with the core verb and the mode split. It wastes some space re-enumerating layout and style examples that the enum already lists in full, which is the only real padding.

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

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

For a 16-parameter generative tool with no output schema, the description should say more about the result: whether an infographic is rendered inline, saved as an artifact needing an ID, or returned as a URL, and whether generation is long-running. Mode selection and source families are well covered, but the post-call story is still missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns more by grouping the eight source parameters into one conceptual family ('notes/webpage/youtube/documents/images/audio/ai_research/ai_chat_context') and reinforcing that title is required in source mode. It also conveys that unit_id produces a preview of the next 3 syllabus sections, adding intent beyond the schema's field-level text.

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

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

States a specific verb and resource ('Generate an AI-powered educational infographic') and immediately splits the tool into its two operating modes (unit_id vs. custom sources). It never names edit_infographic to disambiguate create-vs-edit, but the creation framing is unambiguous enough that an agent will not confuse the two.

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

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

Explicitly tells the agent which mode to pick: unit_id 'for learning roadmap' (course-based) vs. sources 'for any topic' (standalone). It does not state when NOT to use this tool, nor does it route the agent to edit_infographic for modifying an existing infographic.

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

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

Annotations already establish readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the bar is lower. The description adds generation quantity and item structure, but says nothing about latency, cost, failure behavior, or what happens when neither unit_id nor any source is supplied despite auto_research defaulting to true.

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

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

Three tight sentences, front-loaded with the core action and output shape before the mode split. Every sentence earns its place, though the final 'Supports both course-based and standalone modes' partially restates the opening clause.

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 13 optional parameters, no required fields, and no output schema, the description should say more about what is returned (quiz ID, question payload) and what happens with zero inputs. It covers the generation contract well but leaves the return side and default-input edge case unaddressed.

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

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

Schema description coverage is 100%, so every one of the 13 parameters is already documented in structured data. The description reinforces the unit_id-versus-sources mutual exclusivity, but adds no format or precedence details beyond that. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Generate 10 AI-powered match-pair questions') plus the exact output shape (2 sets of 5 pairs). The two sourcing modes are named, which cleanly separates it from siblings like edit_match_pair or create_mcq.

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 clearly frames the two modes — course-based via unit_id or standalone via title + sources — so an agent knows which path to take. It does not explicitly say when to use edit_match_pair instead, nor does it warn about which source parameters can be combined.

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

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

Annotations already declare the mutation and open-world profile (readOnly=false, openWorld=true, destructive=false), so the description only needs to add context. It contributes the fixed count of 5 questions, which is genuinely useful beyond the annotations, but says nothing about source-extraction cost, generation latency, or what happens when neither unit_id nor sources are supplied.

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, zero filler, with the trigger condition and the output quantity leading. The source enumeration is compressed into a single parenthetical rather than a bullet list.

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 13-parameter, zero-required-parameter tool with no output schema, the description covers the two entry paths but omits the fallback behavior handled by auto_research (research generated when only a title is given) and the role of course_id in completion tracking. The rich schema compensates partially, but the description leaves an agent guessing about the no-source case.

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

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

Schema description coverage is 100%, so every one of the 13 parameters is already documented. The description echoes the exclusivity of unit_id vs. sources but adds no syntax, precedence, or format detail beyond what the schema states, matching the baseline for full 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?

States a specific verb and resource ('Generate 5 multiple-choice questions') and pins the output quantity, which lets an agent distinguish it from create_quiz or create_fill_blank without opening schemas. It does not explicitly name the sibling it differs from, so it stops short of a 5.

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

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

Gives an explicit trigger ('when the user asks for multiple choice or MCQ') and the two supported input modes (unit_id vs. source-based). No exclusion or competing-tool routing is stated, so the agent must infer when to prefer edit_mcq or create_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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds useful behavioral facts — Gemini TTS powers the audio, and multi-voice narration/dialog is synthesized — but nothing about generation latency (this is clearly a long-running audio job), whether the response is a URL, job id or inline audio, or how failures surface when neither unit_id nor title is given. No contradiction with annotations; the gap is that a heavy, external-fetching generation tool should say more about outcome.

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

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

Front-loaded with the core verb and mode split, which is correct. However the third sentence, 'Supports both course-based (unit_id) and standalone (sources) modes,' restates the opening sentence's parenthetical verbatim and the 'Creates engaging audio content using Gemini TTS' line is partly marketing filler — two of three sentences are partly redundant.

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

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

For a 13-parameter, zero-required, open-world generation tool with no output schema, the description explains the input modes adequately but leaves the caller without essential context: what is returned (audio asset? URL? async job?), how long it takes, and what happens if invoked with no arguments at all given everything is optional. Adequate but with material gaps for a tool of 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?

Schema coverage is 100%, so all 13 parameters are already documented with descriptions and the baseline is 3. The description groups them concretely by mode (unit_id alone vs title + notes/webpage/youtube/documents/images/audio/ai_research/ai_chat_context), which adds a little organizing value, but supplies no syntax or constraint detail the schema lacks.

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

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

States a specific verb and resource: 'Generate an AI-powered educational podcast' with multi-voice narration and audio synthesis, and splits it into two clear modes (course-based via unit_id vs standalone via sources). An agent can tell what it produces, though it never explicitly names edit_podcast or change_podcast_settings as the tools for modifying an existing podcast instead.

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 two mutually exclusive input modes are described, which is useful routing guidance, but there is no 'use this when...' framing, no mention of what to do instead for modification (edit_podcast/change_podcast_settings are siblings), and no statement of prerequisites. Usage is implied by the mode split rather than stated.

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

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

Adds real behavioral context beyond the annotations: the tool does not generate immediately but 'shows a selector where the user picks the format', which explains why readOnlyHint/idempotent true makes sense for a create-named tool. It does not say anything about content sourcing requirements or what happens after the user picks a format.

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, zero waste, with the usage trigger front-loaded and the selector behavior following. Nothing redundant with the title or annotations.

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?

Annotations plus fully-described schema carry most of the burden for this 13-parameter, no-output-schema tool, and the description covers the dispatch/selector behavior. It omits any hint about the source-selection model (unit_id vs url/notes sources vs auto_research), which an agent must infer purely from the 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 100%, so all 13 parameters (unit_id vs sources, auto_research defaults, media URLs) are already documented in structured form. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Create a quiz') and adds the key differentiator 'without naming a format', which separates it from the many format-specific siblings (create_mcq, create_fill_blank, create_ranking, create_crossword, create_flashcards). An agent can pick this tool without inspecting any sibling schema.

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

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

Gives a clear trigger condition: the user asks for a quiz or to be tested but has not named a format. The inverse condition (use the format-specific tools when a format IS named) is implied by the enumerated formats but never stated as an alternative route.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, and the description adds useful output shape (exactly 5 questions, 4-6 rankable items each). However it never says what is persisted or returned — whether a quiz object is created, an id comes back, or how AI-generation failures behave — which matters for a mutating generation 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?

Three sentences, front-loaded with the action and the mode split, followed by output shape and a closing restatement of the two modes. Nothing is padded; each sentence carries distinct 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 13-parameter, zero-required-parameter tool with two mutually exclusive modes, the description gives the mode logic, conditional requirement, and output shape. It omits what happens when neither unit_id nor sources are supplied with auto_research=false, and whether course_id is required for the completion tracking it hints at.

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 baseline is 3, but the description adds real grouping semantics: it maps the long parameter list into two coherent modes and flags title as conditional on source mode. It also mentions the ranking criteria dimension (chronological, size, importance), which has no corresponding parameter and is purely behavioral context.

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

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

States a specific verb and resource ("Generate 5 AI-powered ranking questions") and immediately names the two input modes (unit_id vs. custom sources). The resource is clearly distinct from siblings like create_mcq, create_flashcards, or create_quiz, so an agent can route without opening the schema.

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

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

Explicitly frames the either/or decision ("existing unit (unit_id) or custom sources") and notes title is required in source mode, which is the key branch an agent must resolve. It stops short of naming alternatives such as edit_ranking for modifying an existing one, or when ranking beats create_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?

Goes meaningfully beyond the annotations by disclosing that changes persist to the database, that the cache is invalidated, that the call is free (no coin cost), and that auth plus ownership are required. Given destructiveHint=true, it would be stronger if it warned that supplying word_clue_pairs replaces the existing set rather than merging.

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

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

Three tight sentences, front-loaded with the operation and editable fields, followed by side effects and access requirements. No wasted wording.

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

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

For a mutation tool with no output schema, it covers persistence, cache invalidation, cost, and authorization. The main gap is not stating whether omitted fields are left unchanged — important for a partial-update tool with destructiveHint=true.

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 five parameters including formats like [width, height] and easy/medium/hard. The description's field enumeration adds little beyond the schema and doesn't clarify partial-update semantics for omitted fields.

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

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

States a specific verb and resource (edit existing crossword puzzle) and enumerates the editable fields (title, word-clue pairs, grid size, difficulty). The word 'existing' implicitly separates it from create_crossword, though no sibling is named explicitly.

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

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

'Edit existing crossword puzzle content' plus 'Requires authentication and ownership' gives the prerequisite context for use. However, it doesn't explicitly say when to use this versus create_crossword or other edit_* tools, nor does it exclude any 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?

Beyond the annotations (destructiveHint=true, openWorldHint=false), it discloses that the diagram is modified and regenerated, that the id must come from an actual prior response, and that each call costs 15 coins — real budget and provenance context the annotations do not carry. It does not say whether prior content is irrecoverably replaced or whether a new diagram id is issued.

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

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

Four short sentences, front-loaded with what the tool does and followed by the prerequisite and cost. 'Modifies the diagram based on your instructions and regenerates' partially restates the opening sentence, a small redundancy in an otherwise tight block.

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

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

For a two-param, non-nested tool with a fully documented schema and annotations covering safety, the description supplies the prerequisite, cost, and mutation model. The one gap is return behavior — with no output schema, an agent cannot tell whether a new diagram_id or artifact is returned for follow-up calls.

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 both parameters are already fully documented, including the provenance constraint on diagram_id and the natural-language character of instructions. The description restates the diagram_id requirement rather than adding syntax, length limits, or example semantics beyond the schema's own example.

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

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

States a specific verb ('Edit') plus resource ('existing Excalidraw diagram') and the mechanism ('natural language instructions'), which cleanly separates it from create_excalidraw and the other edit_* siblings. The pointer back to create_excalidraw as the source of diagram_id reinforces the workflow position.

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?

Makes the precondition explicit ('Requires diagram_id from a previous create_excalidraw response') and indicates the mutation cost, which tells an agent when this call is warranted versus creating anew. It stops short of naming a when-not-to-use case or an alternative editing path, but none exists among the 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?

Adds genuine context beyond the annotations: authenticated caller, ownership requirement, persistence to database, and no coin cost. However, annotations flag destructiveHint=true and idempotentHint=true, and the description says nothing about what is destroyed, whether omitted fields are preserved, or whether edits can be reverted — the key risk information is absent.

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?

Short, front-loaded, and each sentence carries information (what it does, ID provenance, persistence, cost, auth). The all-caps 'IMPORTANT' ID warning is slightly redundant with the schema but is cheap and prevents a common error.

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 8-parameter mutation with full schema coverage and no output schema, the essentials are present: ID provenance, auth, ownership, cost. What is missing is partial-update semantics and any statement of consequences given the destructive hint, which is material for a write tool.

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

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

Schema description coverage is 100%, so all eight parameters are already documented, including the question_id UUID sourcing constraint. The description repeats that constraint rather than adding new 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?

States a specific verb and resource ('Edit existing fill-blank question content'), which distinguishes it from the create_fill_blank sibling and from the other edit_* tools for different question types. It is clear what is being modified, though it never spells out which fields literally constitute the 'content'.

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

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

Usage is implied: use this to modify an already-created question, use create_fill_blank to make new ones (referenced via the response-path hint). There is no explicit 'use this instead of X' or when-not guidance, and no statement that an edit is a full replacement versus a patch.

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 meaningful context they don't cover: persistence to database, cache invalidation, zero coin cost, and authentication/ownership requirements. It stops short of saying whether unspecified fields are left untouched or which of the two addressing modes is preferred.

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

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

Three sentences, front-loaded with the core action, and every clause carries distinct information (editable fields, side effects, cost, auth). 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 an 11-parameter mutation tool, the description never mentions that a card must be identified via flashcard_id or set_id+sequence, nor that it is an all-optional partial update. The schema fills these gaps, so the definition is workable but the description alone is not complete.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented in the schema, including the mutually exclusive flashcard_id vs set_id+sequence modes. The description's parenthetical field list adds only a high-level restatement of what can be edited, not new 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?

States a specific verb (edit) and resource (existing flashcards) and enumerates the editable fields, so an agent can immediately tell it apart from create_flashcards. It never names a sibling explicitly, so differentiation is inferred rather than stated.

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

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

The word 'existing' implies this is the post-creation path versus create_flashcards, and the 'Free (no coin cost)' note helps with cost-sensitive selection. However, there is no explicit when-to-use/when-not statement or named alternative, so routing 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 annotations, it discloses that updates persist to the database, cache is invalidated, the operation is free, and authentication/ownership is required. These are useful behavioral details. It stops short of clarifying partial-update semantics (e.g., whether omitted fields are preserved), which is a notable gap for a destructive edit 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?

Three compact sentences front-load the action and field scope, then add persistence/cache behavior, cost, and auth requirements. Every sentence contributes distinct, useful 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?

The description covers the essentials for a destructive edit operation: what can be changed, that changes are persisted, cache invalidation, cost, and auth/ownership. It would be stronger if it stated whether this is a partial update or full replacement of the provided fields.

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

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

Schema description coverage is 100%, so the schema already documents the parameters and enums. The description adds only a high-level list of editable fields and does not explain partial update behavior or element replacement semantics 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 gives a specific verb and resource: 'Edit existing infographic content.' It also enumerates the editable fields (title, description, layout, visual style, elements), making it clear this differs from create_infographic and from non-infographic edit 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 phrase 'Edit existing infographic content' implies use when modifying an existing infographic, and it states a key prerequisite: 'Requires authentication and ownership.' It does not explicitly name alternatives or exclusions, but the operation is sufficiently self-routing for an edit 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?

Adds genuinely useful context beyond the annotations: updates persist to the database, cache is invalidated, no coin cost, and authentication plus ownership are required. The destructiveHint=true annotation implies overwriting, and the description doesn't clarify whether omitted fields are preserved or cleared, which is the main remaining gap.

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

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

Three short sentences, front-loaded with the core action, followed by side effects and prerequisites. 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?

Covers cost, persistence, cache behavior, and auth/ownership for a 7-parameter mutation tool, which is solid for a definition with full schema coverage and annotations. Slightly incomplete on partial-update semantics (what happens to unspecified fields) and there is no output schema, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100% and every parameter is documented in the schema (including the strict pair_id provenance rule). The description merely restates the field list, adding no format or constraint detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Edit existing match-pair question content') and enumerates the editable fields, which cleanly separates it from the many other edit_* siblings (edit_mcq, edit_fill_blank, edit_ranking). An agent can identify the target resource without opening the schema.

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

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

The word 'existing' plus 'Requires authentication and ownership' implies this applies to already-created pairs, but there is no explicit contrast with create_match_pair or any statement about when-not to use it. Prerequisites are given, alternatives are not.

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

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

Beyond annotations, the description adds useful behavioral context: updates are persisted to the database, cache is invalidated, the operation is free, and authentication plus ownership are required. It does not contradict the destructive/idempotent hints, though it could clarify how omitted fields are handled.

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

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

The description is three tight sentences, front-loads the core action and fields, then adds relevant side effects and prerequisites. Every sentence contributes useful information without 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 mutation tool without an output schema, the description covers persistence, cache invalidation, cost, authentication, and ownership, and annotations carry the safety profile. It could be slightly more complete by clarifying partial-update behavior when optional fields are omitted.

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 input schema already documents all six parameters, including the required question_id. The description merely restates the editable fields, adding little semantic detail 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 gives a specific verb (edit) and resource (existing MCQ question content), and enumerates the editable fields. It clearly distinguishes this tool from creation tools such as create_mcq and broader tools like edit_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 usage by stating it edits an existing MCQ and requires authentication and ownership, but it does not explicitly state when to use this versus alternatives such as create_mcq or edit_quiz. No when-not conditions or sibling routing are provided.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds useful context beyond annotations: it is free, requires authentication, and requires ownership. It does not explain overwrite semantics for omitted fields, but the annotation coverage lowers the burden.

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

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

The description is front-loaded with the core action, then organized into editable fields, language codes, and examples. The language list is long but directly useful for parameter selection, and no sentence is wasted.

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 9-parameter mutation tool with annotations and full schema coverage, the description is largely complete: it covers fields, examples, cost, authentication, and ownership. It could additionally clarify whether omitted fields remain unchanged, but no output schema exists and the core invocation needs are covered.

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 detail beyond the schema by explaining each editable field and listing valid language codes with examples, which helps the agent supply correct values.

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

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

The description states a specific verb and resource: 'Edit existing podcast metadata.' It is clearly a mutation tool for podcast records, though it does not explicitly distinguish itself from the sibling change_podcast_settings tool.

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

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

It explains that all fields are optional except podcast_id, provides concrete examples, and notes authentication and ownership requirements. It does not explicitly state when to use this instead of change_podcast_settings, but the usage context is clear.

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

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

Annotations already declare the mutation profile: readOnlyHint=false, destructiveHint=true, idempotentHint=true. The description usefully adds that updates are saved to the database, the cache is invalidated, the operation is free, and authentication plus ownership are required. It does not spell out partial-update versus replacement semantics for nested sections.

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

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

Three short sentences, front-loaded with the action and editable fields, followed by the key operational notes. There is no filler, and each sentence adds useful 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?

The description covers the important behavioral context for a mutation tool: persistence, cache invalidation, cost, authentication, and ownership. Given the rich input schema and annotations, the remaining gap is minor — it doesn't explain partial update behavior or what the call returns.

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 six parameters. The description lists the editable fields but adds no format, syntax, or replacement semantics beyond what the schema provides, which matches the baseline for high 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 uses a specific verb and resource — "Edit existing quiz content" — and lists the editable fields, so the agent can tell it mutates a quiz. It does not explicitly distinguish itself from close siblings such as change_quiz_settings or create_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 phrase "Edit existing quiz content" implies this is for modifying an existing quiz rather than creating one, and the description states authentication and ownership prerequisites. However, it gives no explicit when-to-use guidance or alternatives to choose among the many sibling quiz tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely new context: writes persist to the database, the cache is invalidated, there is no coin cost, and authentication plus ownership are required. It does not say what happens to fields omitted from the update or whether partial updates overwrite, which is the main remaining gap.

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

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

Three short, front-loaded sentences: what it does, what side effects occur, then cost and auth prerequisites. No filler and no repetition of schema details.

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

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

For a 7-parameter mutation with no output schema, the description covers persistence, cache side effects, cost, and auth/ownership prerequisites, which is most of what an agent needs. The missing piece is whether omitted fields are left unchanged or cleared, which matters given partial-update semantics.

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

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

Schema description coverage is 100%, so every one of the 7 parameters is already documented in the schema, including the careful UUID-provenance note on question_id. The description only restates the field list, adding no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Edit) plus the resource (existing ranking question content) and enumerates the editable fields, so it is clearly distinguishable from create_ranking and from sibling editors like edit_mcq or edit_fill_blank.

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?

Establishes the precondition clearly: the question must already exist, the caller must be authenticated and be the owner. It also notes the operation is free, implicitly contrasting with coin-charging creation tools. It does not explicitly name alternatives or exclusion cases, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: paginated results, progress tracking, metadata, and the fact that calls are free and do not count against rate limits.

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

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

The description is front-loaded with the core action and scope, then adds type definitions and rate-limit context in a compact sequence. Every sentence contributes useful information without 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 two-parameter read-only tool with no output schema, the description covers the main return characteristics (pagination, progress tracking, metadata) and the rate-limit behavior. The only notable gap is the missing explanation of the 'limit' parameter's meaning and constraints.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It does well for 'type' by defining the three accepted values, but it does not explain 'limit' beyond implying pagination, leaving one of two parameters semantically underspecified.

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

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

The description uses a specific verb and resource ('Get courses') and clearly enumerates the three course scopes: enrolled, favourites, and community. An agent can distinguish this retrieval tool from mutation siblings like add_to_liked_courses or remove_liked_course without opening the schema.

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

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

It explains what each supported type means, giving clear context for selecting 'enrolled', 'favourites', or 'community'. It does not explicitly state when not to use this tool or name a sibling alternative, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds meaningful behavior beyond annotations: authentication is required, there is no coin cost, and a missing/uninitialized settings record yields 404.

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 definition is compact and front-loaded: the first sentence states the retrieval purpose and returned fields, followed by concise notes on 404 behavior, cost, and authentication. Every sentence adds useful information without redundancy.

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

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

With no output schema, the description appropriately names the returned preferences and the 404 case. Combined with annotations covering safety and idempotency, it is complete enough for an agent to select and invoke this zero-parameter tool correctly.

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

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

This tool takes zero parameters, so the baseline is 4 and there is no parameter semantics to explain. The description instead usefully lists the settings fields that are returned.

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

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

The description uses a specific verb and resource: 'Get your flashcard generation preferences,' and enumerates the exact settings returned. An agent can distinguish it from the mutation-oriented sibling change_flashcard_settings without opening either schema.

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

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

Usage is clearly implied as a read-only retrieval of current flashcard settings, with useful context that it returns 404 if not initialized. It does not explicitly say when to use this versus change_flashcard_settings or the analogous my_quiz_settings/my_podcast_settings tools, but the alternatives are clear from naming and verb choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it is free with no coin cost, displays a monthly calendar view, and shows event icons with details when days are clicked.

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

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

The description is front-loaded with the main purpose and remains compact. Some UI-specific phrasing ('when clicking on days') is less relevant for an agent, but the text is not bloated.

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 low-complexity, read-only view tool with rich annotations and fully documented parameters, the description covers what the diary contains and how it is presented. The lack of an output schema is partially offset by the calendar-view description, though return-value structure is not detailed.

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

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

Schema description coverage is 100%, and the two parameters (year, month) are fully documented with defaults in the schema. The description adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('View') and resource ('personal learning diary calendar'), then enumerates the activity types shown: logins, learning sessions, achievements, coin transactions. This distinguishes it from sibling tools like my_profile or my_courses, which cover different data.

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

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

Usage is implied by the personal diary framing and the note that it is free (no coin cost), but there is no explicit guidance on when to use this instead of alternatives such as my_profile, nor any exclusions. An agent must infer the appropriate context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds meaningful behavior beyond annotations: it returns a 404 when settings are not initialized, is free with no coin cost, and requires authentication.

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

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

The description is front-loaded with the specific action and resource, then adds the relevant return behavior, cost, and authentication requirements in compact sentences. Each sentence contributes useful information without filler.

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

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

With no parameters and no output schema, the description does a good job covering the returned fields, 404 behavior, authentication, and cost. It could be slightly more explicit about the structure of the returned settings, but it is complete enough for an agent to call this simple read-only tool correctly.

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

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

The tool has zero parameters, so parameter semantics are not a substantive risk and the baseline is 4. The description lists returned setting fields, but that is return-value context rather than parameter guidance.

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

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

The description uses a specific verb and resource: 'Get your podcast generation preferences,' and enumerates the preference fields returned. It is clearly a read operation and is distinguishable from the mutation sibling change_podcast_settings, though it does not explicitly name or contrast that sibling.

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

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

The description implies usage by saying it returns current settings or 404 if not initialized, which gives useful context for when the tool applies. However, it does not explicitly say when to use this instead of change_podcast_settings or other settings-related 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 declare readOnlyHint, idempotentHint, non-destructive, and non-open-world behavior. The description adds substantive context beyond the annotations: it confirms the tool works for both authenticated and anonymous users and that it is free and does not count against rate limits. These are valuable behavioral details for an agent deciding whether to call 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 three tight sentences with zero waste. The primary purpose is front-loaded, followed by audience (auth/anonymous) and cost/rate-limit information, which is exactly the order an agent needs to make a quick call decision.

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?

There is no output schema, so the description bears the burden of explaining the return shape. It lists the key fields (profile, subscription status, coins, XP, groups), which is sufficient for a zero-parameter read tool. Minor gaps include not describing the exact structure or nested objects, but overall it is complete enough to call correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description does not need to explain parameter usage, and no parameter semantics are 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?

The description uses a specific verb ('Get') and resource ('current authenticated user information') and enumerates the returned fields (profile, subscription status, coins, XP, groups). It does not explicitly contrast with sibling tools like 'my_courses' or 'about_quizlink', but the scope is clear enough that an agent can distinguish it from most siblings.

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

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

The description notes that the tool works for authenticated and anonymous/freemium users, which implies broad applicability, and that it is a 'FREE call that does NOT count against rate limits,' which is a useful usage hint. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'use this instead of my_courses when you need profile data') or name any exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description still adds real value beyond them: it is FREE (no coin cost), requires authentication, and returns a 404 when settings have not been initialized.

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

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

Three tight sentences, front-loaded with what is returned, followed by error behavior, cost and auth. The field enumeration is slightly list-heavy but each item carries information the agent cannot get elsewhere.

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-param, no-output-schema read tool, the description covers return shape, error case, cost model and auth requirement, which is everything needed to call it and interpret the result.

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

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

Zero parameters, so the baseline is 4 by rule. Additionally, the description enumerates the data fields the tool surfaces (language, min/max questions, time limit, difficulty values, question types, passing score), which compensates for the absent output 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?

Specific verb ('Get') plus resource ('your quiz generation preferences') and an explicit enumeration of the settings returned. It is clearly the read counterpart to change_quiz_settings and distinguishes itself from my_flashcard_settings and my_podcast_settings by naming the domain.

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

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

Usage is implied (fetch current preferences before generating a quiz, or to check initialization state) but the description never names change_quiz_settings as the mutation alternative or states conditions. 'Returns current settings or 404 if not initialized' is the closest thing to guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering safety. The description adds that the tool includes move validation, opening descriptions, and post-game analysis, but does not explain the return format or interaction model. Moderate added value.

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

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

Single front-loaded sentence with a compact option list. Slightly long but every clause serves to list options or included features.

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 rich schema and safety annotations, the description covers configuration and included features. It omits return values, but for a game-start tool the key aspects are covered.

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 all parameters are fully documented. The description repeats the enum options and examples already present in the schema, adding no new semantic meaning beyond what structured fields provide.

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

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

States a specific verb ('start') and resource ('chess game against an AI opponent'), and distinguishes itself from other game siblings by game type. The 'as a study break' framing adds context without ambiguity.

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

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

Provides an implied usage context ('as a study break') but does not name alternatives or exclusions (e.g., when to choose play_snake or play_memory_game instead). Guidance is present but minimal.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context that it tracks moves, time, and best score, but does not explain what starting a game returns or whether state persists across calls.

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

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

Three short sentences, front-loaded with the action and context. The option list is wasted space because those options do not exist, but overall the description is tight and easy to scan.

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-optional-param tool with annotations and no output schema, the description covers the core action. However, the parameter mismatch (grid/theme vs. difficulty) and lack of return-value context leave a notable gap.

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

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

Schema coverage is 100% for the single 'difficulty' enum, so baseline would be 3, but the description instead describes grid size and theme options that are not parameters at all and never mentions difficulty. This actively misleads an agent about what can be configured.

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

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

States a specific verb and resource ('Start a memory card-matching game') and adds context ('as a study break'). However, it names options (grid size 4x4/6x6/8x8 and theme) that do not exist anywhere in the schema, which slightly muddies what the tool actually starts.

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 'as a study break' implies when to use it, but there is no explicit guidance on when to choose this over sibling games like play_chess or play_snake, nor any exclusions. Usage is implied rather than stated.

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

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

Annotations already establish readOnly, non-destructive, non-open-world behavior. The description adds context annotations cannot: the game runs entirely in the widget and generates no content, plus the in-game mechanics (snake grows, speed increases with score) — a useful cue for what happens after invocation.

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

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

Four short sentences, front-loaded with purpose and followed by gameplay context, then options, then the widget caveat. The options list slightly duplicates the schema but a reader scanning the description benefits from 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?

For a zero-required-parameter, no-output-schema leisure tool the description covers everything needed to invoke it: what starts, what knobs exist, and that nothing external is generated. Only the post-invocation experience (a widget appears with no return payload) is left slightly implicit.

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

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

Schema description coverage is 100% and the description only restates the four options, their enums (easy/medium/hard, classic/timed) and ranges (10-30, 1-10) that the schema already documents in more detail, including defaults. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('Start a game of Snake') and the framing ('short study break') makes it instantly distinguishable from play_chess and play_memory_game. It doesn't explicitly contrast with those siblings, but the named game is unique enough that no ambiguity remains.

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?

'as a short study break' implies the context (leisure between study tasks) but gives no explicit when-not conditions and never names an alternative such as play_chess or play_memory_game. Adequate implied guidance, not routing guidance.

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

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

Annotations already declare destructiveHint, idempotentHint, and readOnlyHint=false, so those facts are baseline. The description adds genuine beyond-schema context: authentication is required, the call is FREE and exempt from rate limits, and idempotency is explained as 'safe to call even if course is not in favorites' rather than merely restated.

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

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

Four short, front-loaded sentences with the core action stated first; each adds a distinct operational fact. Minor redundancy in restating idempotency that annotations already carry.

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?

A simple one-param mutation with no output schema, and the description covers the essential behavioral facts (auth, cost, idempotency). Only the course_id format is left unspecified, a small gap given the tool's simplicity.

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

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

Only one parameter (course_id) with 0% schema description coverage, and the description adds nothing about its expected format or value (e.g., course slug vs numeric ID). With a single undocumented param the description should have clarified it, so this sits at minimum-viable rather than the no-param baseline.

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

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

States a specific verb (Remove) and resource (a course from favorites/bookmarks), making the inverse relationship to add_to_liked_courses immediately obvious. An agent can distinguish it from sibling tools without opening the schema.

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

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

The intent-to-use is clear (when the agent wants to unbookmark a course), and the inverse sibling add_to_liked_courses is implied by the resource. However, the description never explicitly names the alternative or states exclusion conditions, leaving that inference to the agent.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful context that the call is free and does not count against rate limits, plus what the output includes (podium, your position, statistics).

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

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

Four sentences, front-loaded with purpose and followed by filtering and auto_page guidance. No wasted 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?

Given no output schema, the description explains the return content (top performers, your position, detailed statistics). Annotations cover safety, and all parameters are documented in the 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 100%, so all five parameters are already documented. The description reinforces time-range and auto_page behavior but adds little 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?

States a specific verb and resource: viewing competitive rankings and comparing to other learners. The scope is clear, but it does not explicitly differentiate itself from the sibling create_ranking tool.

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

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

Explains how to filter by time range and course, and when to use auto_page=true. However, it does not state when to choose this tool over alternatives or any exclusions.

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 give the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the description's main added value is disclosing the dual create/retrieve behavior via course_id, which the annotations cannot express. It does not say what generation does with the supplied sources (processing, latency, whether it overwrites anything), which would have completed the picture.

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

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

Three short sentences that are front-loaded with the core action, then the when-to-use triggers, then the alternate retrieve mode. No filler and nothing redundant.

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

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

With 13 parameters, no required fields, nested tags, and no output schema, the description omits what the call returns (e.g., whether a course_id is produced for later use) and what happens if topic and course_id are both supplied. Adequate for choosing the tool, but not for predicting the result.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including course_id semantics. The description only restates the accepted source types and the course_id behavior at a summary level, adding little beyond the structured fields.

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

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

States a specific verb and resource ('Create an interactive study course') plus the two input modes: from a topic or from supplied sources. The sentence about structured units with quizzes and flashcards positions it as the container tool, which distinguishes it from sibling builders like create_quiz or create_flashcards, though that differentiation is implied rather than stated.

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

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

Gives clear trigger conditions ('study a topic, prepare for a test, exam or interview, understand a concept, or make a study guide') and a second mode ('Pass course_id to open an existing course'). There is no explicit exclusion or named-alternative routing, 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.