Vocab Voyage

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

Discloses side effect ('Cascades to the leaderboard via DB trigger') and auth requirement ('Requires sign-in'). Annotations are consistent and description adds value beyond them.

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

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

Two concise, front-loaded sentences with no wasted words. Each sentence contributes essential 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?

Covers key effects (leaderboard trigger) and prerequisites (sign-in). No output schema exists, but return value is not critical. Could mention if XP replaces or adds to existing score.

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?

Input schema has 100% description coverage for both parameters. The description does not add new meaning beyond the schema's parameter descriptions, so 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?

Description clearly states it awards score-based XP from a game/activity, differentiating from study-time XP. This provides a specific verb and resource, but lacks explicit differentiation from sibling tools like 'play_game'.

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

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

Implies usage context ('separate from study-time XP', 'Requires sign-in'), but does not explicitly state when to use it vs. alternatives or provide exclusion criteria.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds that it takes a word and sentence but does not specify the return format or other behavioral details like handling of non-existent words.

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 sentence with no waste, front-loaded with the action and immediately clarifies the use case.

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 or return value description. While the tool is simple, a brief note on the output (e.g., a string explanation) would improve completeness.

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

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

The schema description covers 'sentence' but not 'word'. The tool description clarifies 'word' as the target word to explain, compensating for the missing schema description. Overall adds meaning beyond the schema.

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

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

The description clearly states the tool explains a word's meaning within a sentence, with a specific use case for ambiguous words. It differentiates from sibling 'get_definition' which likely provides general definitions.

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?

Mentions 'useful when a word has multiple meanings' indicating context for use. Does not explicitly exclude alternatives but provides clear situational 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?

Beyond the annotations (readOnlyHint=false, etc.), the description reveals key side effects: 'The ticket is emailed to the support team and a confirmation is sent to the user with a 1-business-day SLA.' It also states 'Requires sign-in' and the pricing policy, giving full context on what happens and required conditions.

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

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

The description is front-loaded with the core purpose, then flows through usage, side effects, policy, categories, and auth in a logical order. Every sentence adds unique, valuable information; there is no redundancy or fluff.

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

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

Given the tool's moderate complexity and the absence of an output schema, the description covers all necessary context: when to use, what happens after filing (email, SLA, confirmation), category handling, and authentication requirements. Combined with the rich parameter schema, this is fully complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents each parameter with details and guidance (e.g., category enum descriptions). The prose description largely repeats this information (e.g., billing legacy note) without adding new technical specifics about parameter values or formats.

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

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

The description opens with a specific verb and resource: 'File a real human-followup support ticket on behalf of the signed-in user.' It clearly distinguishes this tool from the sibling tools by focusing on human follow-up and support escalation, making its purpose unmistakable.

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

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

It explicitly states when to use the tool: 'Use this when the user reports a bug, account lockout, complaint about a tutor, or anything Sparkle/the agent cannot resolve from data.' It also provides a category guidance note—'billing (legacy, use account instead)'—which helps avoid misuse.

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

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

Annotations already declare readOnlyHint=true and non-destructive. Description adds that it renders an interactive widget and persists mastery for signed-in users, which is valuable beyond annotations.

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

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

Single paragraph, front-loaded with usage guidance, every sentence adds value. No redundancy or filler.

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

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

Covers purpose, usage guidelines, parameter details, behavioral traits, and alternatives. No missing context for an agent to correctly select and invoke this tool.

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

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

Schema coverage is 67%; description adds meaning for test_family by listing valid values (isee, ssat, etc.) and explains count range (1–10) with default 5, going beyond 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?

Description clearly states the tool generates a multiple-choice quiz for test families, explicitly distinguishes from siblings like get_definition and get_flashcards by saying 'Do not use for... call... 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?

Provides explicit when-to-use ('when the user wants to practice...') and when-not-to-use with alternative tool names. Covers context like widget rendering and mastery persistence.

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 significant behavioral context beyond annotations: it confirms read-only nature (already annotated), specifies authentication and parent-only access, explains default parameter behavior, and warns of error for unlinked children. No contradiction with annotations.

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

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

The description is brief and front-loaded with key constraints ('Auth-only. Parent-only.'), then explains the output and defaults in a few sentences. No wasteful 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?

Given no output schema, the description adequately explains the returned data (accuracy, missed words, duration). It covers parameter defaults, error conditions, and constraints, making it fully informative for this simple read tool.

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

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

Schema coverage is 100% and the schema descriptions already state the defaults. The main description restates these defaults without adding new semantic information. Thus, per the baseline for high coverage, score is 3.

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

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

The description clearly states the tool retrieves a detailed breakdown for a single child's study/quiz session, specifying components like accuracy, missed words, and duration. It distinguishes this from sibling tools like get_session_detail by emphasizing 'child' and 'parent-only', making the purpose unambiguous.

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

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

The description specifies 'Auth-only. Parent-only.' and 'Ownership-gated' indicating when to use and limiting scope to parent-child contexts. It also explains default behavior for missing parameters. However, it does not explicitly mention alternatives among sibling tools, such as when get_session_detail might be more appropriate.

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

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

Adds auth/role requirements, default and max days, and behavior when class_id is omitted (worst-first rollup). Annotations already indicate read-only and idempotent, so description adds valuable context.

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

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

Two sentences, front-loaded with constraints, no redundant information. Every word adds value.

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 auth, role, time window, and usage with/without class_id. No output schema, so return values not required. Adequate for a retrieval tool with good annotations.

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

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

Schema covers both parameters with descriptions; description adds meaningful context for class_id (behavior when omitted) and reaffirms defaults for days. No contradictions.

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 'Aggregate class-level trends across the tutor's classes' with specific time window and optional class_id. It distinguishes from sibling 'get_session_trends' by specifying class-level aggregation and auth role.

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

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

Explicitly states 'Auth-only. Tutor-only.' and provides guidance on when to pass class_id vs omit it to get a rollup. No explicit alternatives listed, but 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 indicate read-only and idempotent, but description adds key details: auth-only, return content (weekly XP rank, rival suggestion), deliberate placeholder for leader, rendering behavior. No contradiction.

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

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

Four sentences that are complete and efficient. Front-loaded with usage, then auth, output, rendering. No wasted words.

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

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

Covers all aspects: usage, auth, return value with components, behavioral rule, rendering, anonymous fallback. No output schema needed as description explains return values sufficiently.

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

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

No parameters exist; description explains all behavior meaningfully. Schema coverage is 100%, and description compensates fully by detailing what the tool does without needing inputs.

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

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

The description specifies exact use cases ('how they're doing, who's ahead, rival, challenge') and distinguishes from siblings like get_my_progress or get_session_detail by focusing on class standing and rivalry.

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 explicit when-to-use scenarios, auth requirement, and behavioral rule about naming the class leader. Also notes anonymous caller handling.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safety. The description adds value by using 'sample' to imply a non-exhaustive list, and provides a usage hint for slug discovery, going beyond structured data.

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

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

Two sentences with no unnecessary words. The first sentence front-loads the action and resource, the second adds a crucial usage hint. Every sentence earns its place.

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

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

For a simple read-only list tool with comprehensive annotations, the description covers the core purpose and a key prerequisite. Absence of output schema or further behavioral details is acceptable given the tool's simplicity and annotation coverage.

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

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

With 50% schema description coverage, the description adds minimal param info beyond the schema. It hints at course_slug usage via 'discover slugs', but doesn't elaborate on limit or format. The schema already documents limit's range and default.

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

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

The description clearly states the tool gets a sample of vocabulary words from a specific course, using the verb 'Get' and specifying the resource. It distinguishes from siblings by mentioning 'sample' and directing users to list_courses for slug discovery.

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

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

The description mentions using list_courses to discover slugs, providing a prerequisite hint. Though it doesn't explicitly exclude alternatives, the context of siblings like get_definition implies this is for listing, not detailed lookups.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds that it returns 'curated dictionary data from the Vocab Voyage corpus,' providing source context but no additional behavioral traits beyond what annotations imply.

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, then usage, then exclusions. No redundant words.

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

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

Given low complexity (1 required param, no output schema, no nested objects), the description provides sufficient context: purpose, usage conditions, exclusions, and data source.

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 covers 100% with description 'The word to define.' The description does not add new semantics beyond the schema, meeting 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?

The description clearly states the tool returns definitions, part of speech, synonyms/antonyms, and example sentences for a specific word. It also distinguishes from siblings explain_word_in_context and get_word_of_the_day.

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 says when to use: 'when the user asks what a specific word means, requests its definition...' and when not to use: 'Do not use for sentence-level meaning disambiguation (call explain_word_in_context) or for daily word prompts (call get_word_of_the_day).' Names alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds context: returns 1-12 cards, renders interactive widget, persistence for signed-in users. No contradictions. Could add more on idempotency but not required.

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 with no waste: first sentence states purpose, second adds behavioral details, third provides exclusions. Front-loaded and structured for quick parsing.

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 2 well-documented parameters, no output schema, and clear annotations, the description covers when to use, what it returns, interactive behavior, and exclusions. No gaps for this tool's 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 schema documents both parameters. Description adds minor context (default count 5, test_family values) but does not significantly improve understanding beyond the schema.

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

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

The description states 'returns 1–12 cards for a test family', uses specific verbs (drill, tap-to-flip review), and distinguishes from siblings by explicitly excluding multiple-choice testing (generate_quiz) and single word lookup (get_definition).

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

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

Explicitly states when to use ('user asks for flashcards, wants to drill words individually, or wants a tap-to-flip review session') and when not to use ('Do not use for multiple-choice testing... or for a single word lookup...'), naming alternatives.

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

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

Annotations already mark readOnlyHint=true. Description adds value by describing rendering behavior (widget vs markdown fallback) and anonymous caller handling, going beyond annotations.

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

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

Four sentences with no wasted words; front-loaded with primary use case and key constraints.

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 auth, rendering, and usage boundaries adequately for a simple 0-parameter tool with no output schema; minor gap on return format but not critical.

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

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

No parameters exist; description adds no parameter info, but baseline is 4 for 0-parameter tools per guidelines.

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

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

The description clearly states the tool is for signed-in users asking about their own streak, XP, words mastered, etc., and explicitly distinguishes from global or other users' progress, matching sibling tool differentiation.

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

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

Provides explicit when-to-use (personal progress queries) and when-not-to-use (global stats, other users), but does not name specific alternative tools, though sibling list implies 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 mark it as read-only and idempotent. The description adds behavioral nuance: returns hours_until_expiry, requires sign-in, and includes a proactive resend rule. No contradictions.

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 usage guidance, then key data and rules. Every sentence adds value 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?

Covers return data (pending invites with hours_until_expiry) and behavioral rules. Lacks explicit mention of response structure (e.g., array of objects), but sufficient for its simplicity and absence of output schema.

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

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

No parameters exist, so schema coverage is 100%. Baseline 4 applies; no additional parameter info needed.

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

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

The description clearly states the tool returns pending parent invites, share codes, or acceptance status. It distinguishes from the sibling tool 'resend_pending_invite' by focusing on retrieval, not resending.

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 says 'Use this when the signed-in user asks about pending parent invites...' and provides actionable rules for when invites are expiring or expired, guiding the agent on next steps.

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 and idempotentHint, but description adds valuable behavioral details: returns up to 25 words, last N days default 7, includes miss-rate and timestamp, links to app page, and requires sign-in. No contradiction with annotations.

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

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

Three sentences with zero waste. Front-loaded with usage condition, then return value details, then presentation guidelines. Every sentence earns its place.

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

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

No output schema exists, so description must explain return value. It covers: what is returned (up to 25 words), timeframe (last N days), fields (miss-rate, timestamp), and a link. Also includes how to present results to user. Lacks exact structure of a word object but sufficient for a read-only list.

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

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

Schema has 100% coverage for both parameters (days and limit). Description adds default for days (7) and mentions 'up to 25 words' which loosely aligns with limit but is slightly inconsistent with schema's max 50. No significant added value beyond 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?

Description clearly states the tool retrieves words the user got wrong, missed, or wants to review. It specifies the resource (words) and action (get recent mistakes), and distinguishes from sibling tools like get_course_word_list or get_flashcards.

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 when to use (user asks about mistakes, missed words, etc.) and provides a usage instruction to summarize results. Does not mention when not to use or list alternatives, but the context of siblings makes it clear.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by stating it's a hint derived from lifecycle phase. No contradictions and no missing behavioral traits for this simple read tool.

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

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

The description is extremely concise—one sentence plus a usage note—with no wasted words. Every part earns its place.

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

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

For a simple tool with one optional parameter and no output schema, the description adequately explains purpose and usage. It could mention what the hint looks like, but it's not critical.

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

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

Schema coverage is 100% with a clear description for the single optional parameter. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: to provide a one-line 'do this next' hint derived from the user's lifecycle phase. It distinguishes from a full guidance card, implying a lighter alternative, but does not explicitly differentiate from siblings like get_sparkle_guidance.

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

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

The description provides context for when to use (quick recommendation over full guidance card) but lacks explicit when-not-to-use or alternative tool references.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the description adds value by detailing return fields and truncation limits (max 10 wrong words, first 20 timeline events). This provides behavioral context beyond the annotations.

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

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

The description is well-structured with front-loaded use case, followed by parameter guidance, return fields, and an agent instruction. It is slightly verbose but every sentence adds value. Could be more concise, but no fluff.

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

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

Despite lacking an output schema, the description fully explains the return value (title, accuracy %, wrong_words up to 10, timeline up to 20 events) and provides an instruction to the agent to cite specific fields. This is complete for the tool's simplicity.

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

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

Schema coverage is 100%, but the description adds meaning by explaining how to obtain session_id (from get_recent_session_results or picker chip) and that include_timeline defaults to true. This enriches the parameter semantics beyond the schema descriptions.

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

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

The description clearly states the tool returns session details (title, accuracy, wrong words, timeline) and specifies the exact user queries it addresses ('what did I miss', 'which words tripped me up', 'accuracy on session X'). It also distinguishes from siblings by focusing on a single session, referencing get_recent_session_results as the source for session_id.

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

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

The description explicitly tells when to use this tool (user asking about session specifics) and how to obtain the session_id (from get_recent_session_results or picker chip). It does not explicitly exclude alternatives like get_session_trends, but the context is clear enough for an agent to decide.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint. Description adds 'Auth-only' and window constraints, providing useful behavioral context beyond annotations.

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

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

Two sentences, front-loaded with key information, no extraneous words.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description sufficiently lists return values and constraints, making it 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 coverage is 100% and already documents the 'days' parameter with default and max. The description repeats this information without adding new meaning, so baseline score is appropriate.

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

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

The description clearly states 'Personal study trends over a window' and lists specific outputs (session count, total minutes, accuracy trend, top-missed words), distinguishing it from siblings like get_class_session_trends.

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 when to use: after user asks about trending, improving, or top-missed words. Does not mention when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint and destructiveHint, but description adds valuable context: it renders the session-debrief widget (a side-effect on client) and handles anonymous callers with visitor.* phase. This goes beyond annotation info and helps the agent understand behavioral traits.

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

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

The description is extremely concise: two sentences that front-load the main return content and then cover widget rendering and anonymous behavior. Every sentence adds unique value, no wasted words.

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

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

The description explains the return values (phase, greeting, recommendations, CTA) and mentions widget rendering and anonymous handling. Without an output schema, it provides enough context for an agent to understand the tool's output, though a formal structure or example would improve completeness.

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

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

The schema coverage is 100%, and the schema description for the only parameter 'persona' is clear. The tool description does not add additional semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Description clearly states the tool returns lifecycle-aware guidance including phase, greeting, recommended tool calls, and optional CTA. It distinguishes itself from siblings like get_recommended_next_action by mentioning widget rendering and anonymous visitor handling.

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 in the context of Vocab Voyage for session debrief, but does not explicitly compare with similar tools like get_recommended_next_action or provide exclusion criteria. The context is clear but lacks direct guidance on alternatives.

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

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

Annotations already set readOnlyHint=true, so the agent knows it's non-destructive. The description adds that it is auth-only, returns a plan based on trends, and inlines only the first 3 days with full plan persisting on click. No contradictions with annotations.

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

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

Two sentences, front-loaded with 'Auth-only', no fluff. Every phrase earns its place, covering authentication, personalization, duration, modes, and UI behavior.

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

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

Given the tool has only one parameter and no output schema, the description covers authentication, plan characteristics, and display behavior. It lacks details on error handling or return structure, but those are not critical for this read-only tool with simple inputs.

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

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

Schema coverage is 100% with a single parameter 'horizon_days' described in schema. The description adds value by specifying default (7) and valid range (3–7), which is not in the schema description.

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

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

The description clearly states it returns a personalized study plan with specific focus modes and duration range. It differentiates from generic plan tools by mentioning 'weak-topic-drill / streak-recovery / new-words / review-mastery' modes, but doesn't explicitly contrast with siblings like 'study_plan_preview'.

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 specifies 'Auth-only' and describes when to use (personalized plan based on trends). However, it does not provide explicit guidance on when not to use this tool or compare to alternatives like 'study_plan_preview' or 'get_recommended_next_action'.

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

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

The description adds context beyond annotations by stating the tool is 'deterministic' and detailing the return fields (definition, part of speech, example, synonyms/antonyms). Annotations already indicate readOnlyHint, idempotentHint, etc., and the description aligns with them without contradiction.

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

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

The description is concise (3 sentences) with front-loaded purpose. Every sentence adds value: usage context, return details, and an explicit alternative. No extraneous information.

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

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

For a simple read tool with one optional parameter and no output schema, the description covers purpose, usage guidelines, return fields, alternatives, and parameter scope comprehensively. It is complete for the given 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?

The input schema already has 100% description coverage for the only parameter 'test_family', listing valid values. The description merely restates that it's 'optionally scoped to a test family' without adding new semantics, meeting 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 clearly states that the tool returns today's Word of the Day with specific fields (definition, part of speech, example, synonyms/antonyms). It explicitly distinguishes itself from the sibling tool 'get_definition' by stating 'Do not use for arbitrary lookups — call get_definition 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 description provides explicit usage guidance: 'Use this when the user asks for today's word, a daily vocabulary nudge, or a single-word warmup.' It also clearly states when not to use it and directs to 'get_definition' for arbitrary lookups, providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral traits beyond confirming it lists courses with slugs and descriptions, which is consistent.

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

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

The description is a single, efficient sentence that front-loads the action and result. Every word is necessary, with no redundancy or filler.

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

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

For a parameterless tool with no output schema, the description provides sufficient detail: it lists all courses with slugs and descriptions. It does not explain return format, but given the simple list nature, it is nearly complete.

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

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

There are no parameters, so schema coverage is 100%. The description adds meaning by specifying the output includes 'slugs and descriptions', which the schema alone does not convey. Baseline 4 is appropriate.

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

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

The description clearly states the tool lists all Vocab Voyage courses (13 total) with slugs and descriptions. It uses a specific verb 'Lists' and resource 'courses', distinguishing it from sibling tools like get_course_word_list which filters by course.

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

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

No explicit when-to-use or alternatives are given, but the simplicity of the tool (no parameters) makes its purpose obvious. It is implied that this tool is for retrieving the full course list, with no sibling tool offering the same functionality.

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. The description adds context about the content (starter prompts) and relationship to standard endpoint, but no behavioral details beyond annotations.

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

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

Two concise sentences, each providing essential information without unnecessary words.

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

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

Given no parameters and no output schema, the description adequately explains what the tool does and its output, making it complete for a simple list operation.

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

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

No parameters, so schema coverage is 100%. The description adds no parameter info, which is fine; baseline for 0 params is 4.

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

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

The description clearly states it lists Vocab Voyage's MCP starter prompts, and notes they are also exposed via the standard prompts/list endpoint, distinguishing it from other list tools.

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

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

Explicitly states it is 'Useful for hosts that don't yet support prompts/list', guiding when to use this tool versus relying on the standard endpoint.

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 provide idempotentHint=true and destructiveHint=false. The description adds valuable context about resetting mastery and requiring sign-in, which goes beyond the annotations and clarifies the mutation behavior.

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

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

The description is a single sentence that efficiently conveys purpose, effect, and prerequisite. Every word adds value with no redundancy.

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

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

While the main action is clear, there is no mention of return value, success/failure indicators, or prerequisites beyond sign-in. Given no output schema, the description could be more complete for a mutation 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 0%, and the description does not explain the two parameters ('word' and 'card_id'). The agent is left guessing their roles and whether both are needed, which is a significant gap.

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

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

The description clearly states the tool marks a word as 'still-learning' and resets mastery, which distinguishes it from 'mark_word_known'. The verb 'mark' and resource 'word' are specific and unambiguous.

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

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

The description indicates this is for manual marking and requires sign-in. It doesn't explicitly contrast with sibling tools like 'mark_word_known' or 'record_word_result', but the context is clear enough for an agent to infer appropriate use.

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 the requirement of sign-in, which is not in the annotations. However, beyond that, it does not elaborate on mutability or idempotency. The idempotentHint and destructiveHint are already declared, so this is adequate but not exemplary.

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

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

The description is extremely concise with two sentences, front-loading the core action. Every word serves a purpose without unnecessary detail.

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

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

Given the tool has two optional parameters and no output schema, the description is somewhat complete in describing the action, but it omits parameter details and expected return values, which are needed for full understanding.

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

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

With 0% schema description coverage, the description should clarify the two parameters. It fails to mention 'word' and 'card_id' at all, leaving the agent to guess their roles.

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

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

The description clearly states the tool marks a word as mastered for the signed-in user, analogous to the 'I knew this' flashcard override. However, it could more explicitly distinguish it from the sibling tool 'mark_word_difficult'.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'mark_word_difficult' or 'record_word_result'. It only mentions 'requires sign-in', which is a prerequisite, not a usage condition.

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?

Discloses rate-limiting with 24h cooldown and that response includes 'retry_after_hours'. Mentions email fallback and push notification. Annotations indicate mutation (readOnlyHint=false) but no destructiveness (destructiveHint=false), and description adds behavioral details beyond annotations without contradiction.

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

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

Four sentences, front-loaded with 'Parent-only.' Includes all essential information without verbosity. Every sentence adds value: who can use, what it does, when to use, rate limit info, and important warnings.

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, so description must explain return behavior. It covers rate limit error response with retry_after_hours and mentions sign-in requirement. Could be more complete by specifying success response format, but given the tool's simplicity, it's sufficient.

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

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

Schema descriptions cover all three parameters (100% coverage), so baseline is 3. Description adds character limits (≤200 for reason, ≤280 for message) and optionality, which provides minor added value but doesn't fundamentally change understanding.

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

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

Description clearly states it sends a 'check-in' push notification and email fallback from parent to child. It specifies 'parent-only' and gives example use cases, distinguishing it from other tools like 'award_game_xp' or 'get_child_session_detail'.

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 explicit when-to-use scenarios with quoted phrases like 'remind my kid to study'. Includes important constraints: parent-only, requires sign-in, no spoofing. Lacks explicit when-not-to-use, but context is clear enough.

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

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

Description comprehensively explains side effects beyond annotations: launches game, renders widget/deep link, persists answers via record_word_result, fires record_session_complete and award_game_xp, and contributes to streaks/XP/mastery. No contradictions with annotations.

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

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

Front-loaded with usage guidance, but includes an exhaustive slug list that is already in the schema. Still reasonably concise and well-structured.

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

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

Given no output schema, description covers return behavior (widget vs deep link), side effects, and integration with other MCP tools. Complete for a game launching tool with three parameters.

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

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

Schema coverage is 100% and description largely repeats schema info. While it lists allowed slugs, it adds minimal new meaning beyond what schema already 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?

Clearly states the tool plays a vocabulary game with 11 specific mini-games. Distinguishes from sibling generate_quiz by explicitly warning against using it for serious test-prep quizzes.

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

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

Explicitly details when to use: 'when the user wants to play a vocabulary game, asks for something fun, or wants to learn through play.' Also specifies when not to use and directs to generate_quiz as the alternative.

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

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

The description discloses behaviors beyond annotations: it specifies writing to study_sessions, the XP formula (+1/min capped 30/day), and daily streak updates. Annotations indicate readOnlyHint=false (write operation) and destructiveHint=false, with no contradiction.

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

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

Two compact sentences: first covers the core functionality, second provides usage guidance. No redundant information.

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

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

No output schema exists, but the description explains the tool's effects (writes to tables, awards XP, updates streak). For a recording tool with 7 parameters, it covers the main behaviors, though it omits error cases or return value details.

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

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

Schema coverage is low (29%), but the description adds context for deck_id (optional, omit for ad-hoc sessions) and implies the role of cards_studied and time_spent_seconds. It does not detail total_count, correct_count, session_title, or session_type, leaving ambiguity.

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

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

The description uses the specific verb 'record' and identifies the resource as a 'completed study session'. It outlines three distinct actions (writes to study_sessions, awards XP, updates streak), distinguishing it clearly from sibling tools like play_game or generate_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 explicitly states when to use the tool ('after a play_game / quiz / flashcard session ends') and notes a prerequisite ('requires sign-in'). It does not mention when not to use it or alternative tools, but the context of sibling tools is available.

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 explicitly labels the action as 'persist' (write), consistent with annotations (readOnlyHint=false). It adds behavioral context about leaderboard/streak impact, which annotations do not provide. No contradictions.

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 adding value: action, behavioral impact, prerequisite. No wasted words. Front-loaded with the primary purpose.

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

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

The description covers key aspects (leaderboard, sign-in) but omits details on parameter selection (word vs. card_id), success feedback, and error cases. With 7 parameters and no output schema, more guidance is needed for a complete understanding.

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 57%, leaving three parameters (is_correct, selected_answer, time_taken_seconds) without schema descriptions. The description only clarifies is_correct via 'correct/incorrect', but fails to explain selected_answer or time_taken_seconds, which an agent needs for correct invocation.

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 ('Persist') and resource ('single word answer to mastery progress'), clearly distinguishing it from sibling tools like mark_word_known (which marks known state) or mark_word_difficult (difficulty level). The mention of mirroring web app scaling adds specificity.

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

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

The description states 'Requires sign-in' as a prerequisite but provides no explicit when-to-use or when-not-to-use guidance relative to alternatives such as mark_word_known or get_flashcards. An agent is left to infer context from the action verb.

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

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

Beyond annotations (which indicate non-readonly, non-destructive), the description adds key behaviors: it re-emails the existing token without generating a new code, imposes a 60s cooldown, requires ownership, and needs sign-in. No contradictions with annotations.

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

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

The description is concise with four sentences, each adding unique value. The main action is front-loaded, and there is no redundant or extraneous 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 the simplicity of the tool (one parameter, no output schema), the description provides sufficient contextual completeness: when to use, behavioral details, cooldown, and prerequisites. No gaps are apparent.

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

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

The single parameter invite_id is fully described in the schema (100% coverage) as the id from get_pending_invites. The tool description adds no additional parameter information, so the baseline score of 3 is appropriate.

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

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

The description states the tool resends a pending parent invite by ID, using a specific verb and resource. It implicitly distinguishes from the sibling get_pending_invites by focusing on resending rather than listing.

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

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

The description explicitly specifies when to use the tool: after get_pending_invites shows an invite expiring soon or when the user asks to resend. It does not mention when not to use or alternative tools, but the context is clear enough.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it's session-scoped and links to the guidance tool, providing useful behavioral context beyond the annotations.

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

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

Two concise sentences with no waste. Every sentence adds value: the first defines the action and values, the second explains scope and integration.

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

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

For a simple, single-parameter tool with no output schema, the description is complete. It covers what the tool does, allowed values, session scope, and how it should be used in conjunction with get_sparkle_guidance.

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 fully documents the 'persona' parameter with its allowed values. The description repeats these values but adds no new semantic information 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 clearly states the tool's purpose: to bias Sparkle guidance toward a specific persona. It lists the allowed values (student, parent, tutor, explorer) and distinguishes itself from the sibling tool 'get_sparkle_guidance' by setting context rather than retrieving guidance.

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

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

The description provides usage context: session-scoped and the host should pass the chosen persona back to get_sparkle_guidance. It doesn't explicitly state when not to use it, but the context makes the usage clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to cover safety. It adds behavior details: returns a 7-day plan (5 words/day), renders an interactive widget, and launches flashcard sessions. However, it does not mention error handling for invalid inputs.

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 serving a purpose: usage conditions, return value, exclusions. No redundancy or unnecessary words. Front-loaded with the core purpose.

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

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

With no output schema, the description adequately explains the return (plan and widget). It covers the main use cases and differentiates from siblings. Missing potential edge cases (e.g., unsupported test_family) but sufficient for typical use.

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 50%, and the description adds context: it mentions 'given test family' and 'by date,' clarifying that test_family is required and target_date is optional. It does not provide format details beyond the schema, but the added semantics are sufficient.

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

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

The description clearly states the tool's purpose: 'Use this when the user asks for a study plan...' and specifies it returns a 7-day plan. It distinguishes from siblings by explicitly naming generate_quiz and get_definition as alternatives.

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

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

The description provides explicit when-to-use and when-not-to-use guidance, including direct references to sibling tools: 'Do not use for a single quiz session — call generate_quiz instead. Do not use for one-off lookups — call get_definition instead.'

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds only that it delegates to a web app function and requires sign-in. No detail on side effects, idempotency, or what 'promotion logic' entails. Given the lack of annotation detail, the description should provide more behavioral context.

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

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

Two sentences with no waste. The key action is front-loaded. However, conciseness sacrifices necessary detail.

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

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

With no output schema and high parameter count with zero schema descriptions, the description fails to provide a complete picture. Missing return value, parameter meanings, and usage scenarios make it inadequate for proper tool selection and invocation.

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

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

Schema description coverage is 0%, and the description offers no explanation for any of the four parameters (course_id, total_count, correct_count, words_studied). This leaves the agent unable to understand how to supply values correctly.

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 it runs adaptive-mastery promotion logic, which is specific to the tool name. It distinguishes from sibling tools by focusing on promotion logic rather than retrieval or other actions. However, it does not explicitly state the outcome of updating the level.

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

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

No guidance on when to use this tool versus alternatives like get_recommended_next_action or record_word_result. The only context is that it requires sign-in, which is minimal.

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