Flash

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

It states the effect (allowing extra new cards) and the return value (total extra granted today). It does not mention whether multiple boosts accumulate or whether they affect only today's quota, but the 'today only' phrasing is transparent enough.

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 tight sentences cover the action, scope, and return value. No fluff or redundancy; the structure is efficient and easy to parse.

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

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

Given the output schema exists and the description already covers purpose, parameters, scope, and return, nothing essential is missing. The tool's behavior is fully understandable from the description.

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

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

Both parameters are fully described in the schema and reinforced in the description: deck (optional, account-wide if omitted) and extra (count, range 1-500). No ambiguity remains.

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

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

The description clearly states the action ('Allow extra new cards for today only'), gives a concrete usage example, and distinguishes scope (deck vs account-wide). It is specific about the resource and the temporary nature.

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 a clear usage scenario ('give me 10 more new cards today') and highlights the key differentiator ('for today only'). It does not explicitly compare with set_limits or other sibling tools, but the temporal scope is evident.

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 (readOnlyHint=false, destructiveHint=false) already signal this is a non-destructive write. The description adds meaningful side-effect disclosure: the deck is created if it doesn't exist, which is not obvious from annotations. It also sets expectations for card content (single clear question, concise answer) that affects study session behavior. 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 no filler. The core purpose is first, followed by a batching recommendation and card-format guidance. Every sentence earns its place, and the description is appropriately short for the tool's complexity.

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

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

With an output schema present, the return format is covered elsewhere. The description covers the tool's behavior (creating cards, auto-creating deck), usage pattern (batch), and input formatting (front/back quality). Nothing an agent needs to call it correctly is missing.

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

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

Schema covers the deck parameter and the tags sub-field, but front and back have no schema descriptions. The description directly addresses this gap by specifying what fronts and backs should be ('single clear question' and 'concise answer'), adding semantic meaning beyond the schema. This compensates for the 50% 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 the exact action (create flashcards), the target resource (a deck), and a key nuance: the deck is created if missing. This clearly differentiates it from create_deck (which creates only the deck) and from update_card/delete_card. An agent immediately knows what this tool does and how it differs from 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?

Gives a concrete use case ('turning pasted notes into cards') and advises batching all cards into one call, which is actionable guidance. It does not explicitly name alternatives like create_deck, but the 'created if missing' clause implies you don't need to pre-create the deck. Lacks an explicit 'when not to use' statement, so not a 5.

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

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

The description adds the behavioral detail that the deck is created empty, implying no cards are added. Annotations already indicate readOnlyHint=false and destructiveHint=false, and the creation action is consistent with those hints. No additional side effects or modifications are mentioned, but the description provides a useful nuance beyond the annotations.

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

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

The description is a single, concise sentence with no redundant phrases. It is well-structured and directly conveys the core action without extraneous 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?

The tool is simple, but the description omits details about return values or expected outcomes (though an output schema exists). Combined with the lack of parameter explanations, the description provides only partial context. However, the core operation is straightforward enough that an agent could likely use it correctly with minimal additional inference.

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

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

The input schema has two parameters (name and description) with no descriptions, and the tool description does not explain their meanings or constraints. Schema description coverage is 0%, and the description does not compensate by clarifying that 'name' is the required deck title and 'description' is an optional textual note. The agent would need to infer parameter semantics from naming conventions alone.

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

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

The description 'Create a new (empty) deck' clearly states the action (create) and the resource (deck), and the parenthetical '(empty)' distinguishes it from card-related tools such as create_cards. It is unambiguous about the tool's primary purpose.

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 only what the tool does, not when to use it versus alternatives. There is no explicit guidance on conditions or trade-offs compared to sibling tools like create_cards or list_decks, though the simplicity of the operation makes the appropriate use case inferable.

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 transparently discloses that the first call performs no deletion and returns a confirm_token, and that the second call, after user confirmation, uses the same card_id and confirm_token to complete the deletion. This goes beyond the annotations by explaining the side-effect-free initial step.

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, well-structured, and communicates the two-step deletion process in two clear sentences. There is no redundant or 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?

The description gives enough context for the tool's invocation flow, including the first call's token return and the second call's required inputs. It does not elaborate on failure cases or the second call's return value, but these are not critical for correct usage given the available annotations and output schema indication.

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 confirm_token parameter is well described in both the schema and the description. The card_id parameter lacks an explicit schema description, but the description's mention of 'same card_id' and the tool's purpose make its meaning clear. The confirmation flow provides additional context that compensates for the partial schema coverage.

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

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

The description clearly states the tool's purpose: delete a card, and it differentiates from sibling tools like delete_deck and update_card by specifying the card-level deletion. The two-step confirmation flow is also described, making the intended operation 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 explains when to use the tool (to delete a card) and outlines the two-step confirmation process. It does not explicitly contrast with alternatives such as delete_deck, but the card-specific language is sufficient for appropriate selection among the listed sibling tools.

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

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

The description discloses the destructive, permanent effect and the two-step confirmation safety mechanism. This aligns with the destructiveHint=true annotation and adds important behavioral context about the first call not deleting anything.

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 and well-structured, with the core action stated first followed by the necessary procedural detail. No unnecessary words or repetition.

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

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

Given the output schema exists and the destructive confirmation flow is fully described, the agent has all necessary context to invoke the tool correctly. The sibling tool list further disambiguates it from related deck/card operations.

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

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

The schema already covers both parameters with clear descriptions, and the tool description reinforces the confirm_token lifecycle. The added value is modest because the schema itself is highly informative, but the confirmation flow is well explained.

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

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

The description clearly identifies the action (delete deck), the resource affected (deck and its cards), and the permanent nature of the operation. It also distinguishes this from delete_card by specifying the deck-level scope.

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

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

It provides explicit step-by-step guidance: omit confirm_token on first call, return the token, and only pass it back after user confirmation. This leaves no ambiguity about when and how to invoke the tool.

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

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

The annotations indicate readOnlyHint=false, so the tool modifies state, but the description does not elaborate on side effects (e.g., whether it marks the session as ended, whether calling it multiple times has different effects, or what happens if the session is already ended). The description does mention it returns a summary, which is helpful, but it leaves some behavioral details implicit.

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 and well-structured. It uses two short sentences to convey the action, the output, and the expected user-facing summary. No redundant or vague wording is present.

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 sibling tools (start_study_session, submit_review, etc.), the description provides sufficient context for an agent to understand the tool's role in the study session workflow. It could be more explicit about session state requirements, but the overall context is adequate.

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

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

The schema provides only a required integer session_id with no description (coverage 0%). The tool description does not elaborate on what session_id refers to, though the tool's purpose makes it reasonably inferable. The description adds no extra clarity beyond the parameter name and the tool's function.

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 end a study session and retrieve its summary. It also specifies the output format (counts by rating and total reviewed) and instructs the agent to give a one-sentence recap, making the intent 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 explains what the tool does but does not explicitly state when to use it relative to sibling tools (e.g., after completing all reviews, or to close an active session). It lacks guidance on preconditions or alternatives, though the tool name and context imply it should be used after start_study_session.

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

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

The description is non-mutating in tone ('Show') and the annotations already declare readOnlyHint=true and destructiveHint=false. It adds useful context that the returned numbers are what the account/decks 'can still serve today,' which implies computed remaining capacity.

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, dense sentence with no filler, redundant wording, or repeated schema information. Every phrase adds information about what the tool returns.

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

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

Given that the tool takes no input, the description fully covers the output context: account defaults, extra new cards granted today, per-deck overrides with null semantics, and remaining new/due counts. No additional context is necessary to call the tool.

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

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

The tool has no parameters and the input schema is empty, so there is no parameter detail for the description to clarify. This matches the baseline for a zero-parameter tool.

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

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

The description states a specific verb ('Show') and a precise resource ('today's study limits'), and enumerates exactly what is returned: account defaults, per-deck overrides, and remaining new/due card counts. There is no ambiguity about the tool's purpose.

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

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

The description makes it clear this is the read/query operation for study limits and includes the relevant scope ('today'), so an agent can select it when checking capacity. It does not explicitly contrast itself with set_limits or boost_new_today, but the intended use is inferable.

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, establishing the safe read-only nature. The description adds no further behavioral disclosure, such as pagination behavior, rate limits, authentication requirements, or any side effects. The mention of filters is parameter-level, not behavioral. With annotations covering the safety profile, the lack of additional context yields a low score.

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

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

The description is a single, front-loaded sentence that states the primary action and the optional filters. Every word contributes to understanding the tool's purpose. There is no redundant information, making it appropriately sized and well-structured.

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

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

For a simple read-only list tool with an output schema and only three optional parameters, the description is mostly adequate. It covers the core functionality and filtering options. However, it does not mention default behavior or pagination, and the limit parameter is undocumented both in schema and description. Given the output schema likely defines the return shape, the description remains sufficient for a straightforward tool, but a note about limit or result size 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?

Schema description coverage is 67%: deck and search have descriptions, limit does not. The description echoes the deck and search filters but does not mention limit or explain its semantics. It adds marginal value over the schema by confirming the filter types, but it does not compensate for the undocumented limit parameter. This falls between high and low coverage, so a baseline of 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'cards', and mentions optional filters (deck name or search term). This unambiguously distinguishes it from card mutation tools like create_cards, delete_card, and update_card, and from list_decks which targets a different resource.

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

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

The description implies when to use this tool (to retrieve cards with optional filtering) and gives context about the filtering options. It does not explicitly contrast with list_decks or other read operations, but the resource difference is obvious. No exclusions are stated, 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?

The annotations already indicate readOnly=true and destructive=false, so the safety profile is covered. The description adds output specifics (due/new counts) but does not discuss side effects or failure modes, which is acceptable for a simple read-only list.

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 clear sentence with no redundant words. It efficiently conveys the tool's purpose and output.

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

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

For a no-parameter listing tool, the description is complete. It tells the agent what is returned (decks with due and new card counts) and there are no additional prerequisites or context requirements.

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 to describe, so the schema fully covers this dimension. No additional parameter explanation is needed.

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

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

The description clearly states the action (list), the resource (user's decks), and the specific data returned (due and new card counts). It unambiguously distinguishes this from card-level operations.

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 is self-explanatory for a no-parameter listing tool. It does not explicitly contrast with list_cards, but the resource difference is obvious enough that an agent can select this tool correctly.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description adds useful behavioral details about override semantics and field omission. The behavior is fully disclosed; no hidden side effects are implied. A small deduction because it does not explicitly state that the operation is non-destructive, but the annotation covers that.

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

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

The description is compact and information-dense, using a parallel structure that makes the two modes (with/without deck) and the sentinel behavior easy to parse. No redundant phrasing or filler.

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

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

Given the presence of an output schema and the straightforward semantics of setting limits, the description covers all necessary context: what the tool does, how the deck parameter changes behavior, how to clear an override, and how omitted fields are handled. No additional context is needed.

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

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

All three parameters are described both in the schema and in the description, with the special -1 meaning for deck overrides and the distinction between account-level and deck-level application. The description adds value beyond the schema by clarifying the context-dependent behavior of 'deck' and the sentinel value.

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

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

The description clearly states the tool's function ('Change daily study limits') and distinguishes it from related operations by specifying the account-default versus deck-override distinction. It is immediately obvious how this differs from 'get_limits' or other sibling 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 explains when to use with or without a deck, describes the -1 sentinel for clearing overrides, and notes that omitted fields are left unchanged. This provides complete guidance for correct invocation without needing external context.

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

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

The annotations already mark this as read-only and non-destructive. The description adds useful behavioral context by saying the answer should be read aloud and followed by a specific submit_review call, but it does not fully explain whether show_answer itself has no other effects. This is still a good amount of added 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 short, direct, and free of unnecessary details. It packs the purpose, usage condition, and required follow-up into two sentences without any fluff or redundancy.

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

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

The tool's purpose, trigger condition, and post-action are all covered. The actual return shape is not described, but since the instruction says to 'read it aloud,' an agent understands that the output is the answer text. Minor gap: it does not address what to do if no card is found or if the card_id is invalid.

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 only parameter, card_id, is not described in the tool description. The parameter name is fairly self-explanatory and the description mentions 'a card's back,' but with 0% schema description coverage, the description should compensate more by explicitly tying card_id to the card being queried.

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

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

The description clearly states the tool's function: 'Get a card's back (the answer).' It also distinguishes this from study/review actions by framing it as the 'answer' reveal, so an agent can easily tell it apart from related tools like list_cards or submit_review.

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

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

The description explicitly says when to use it: 'Use when the user gives up or asks for the answer.' It also provides the exact follow-up action, 'read it aloud, then call submit_review with rating 1,' leaving no ambiguity about the intended workflow.

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

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

The description discloses what the tool returns ('first card's front', 'how many cards are due', 'grading_mode') and instructs the agent on subsequent behavior ('follow its instruction exactly for the whole session'). It also reveals what internal fields are not to be read aloud, showing transparency about output handling.

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 moderately concise and logically structured, with each sentence serving a distinct purpose (what it does, when to use, what it returns, how to behave). It contains some redundancy but remains focused and readable, warranting a score above average.

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

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

Given the tool's complexity (starting a session, returning graded content, and setting a behavioral contract), the description covers all essential aspects: trigger conditions, output contents, and post-call instructions. No critical context is missing for an agent to use the tool correctly.

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

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

The schema already provides 100% coverage with descriptions for both parameters ('tag' and 'deck'). The tool description adds no additional parameter meaning, so the baseline score of 3 applies per the rubric.

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 starts a study session and explicitly lists the trigger conditions ('whenever the user asks to study, review, practice, quiz, test, or drill their cards'). It also clarifies the intended behavior ('Do not quiz from memory: only sessions record progress'), leaving no ambiguity about the tool's purpose.

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 provides explicit when-to-use guidance by naming the exact user intents that should trigger this tool, including edge cases ('even cards created moments ago'). It also differentiates from alternative behavior ('Do not quiz from memory') and explains why this tool is required for progress tracking.

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 key side effects: it records the result, retrieves the next card, and may end the session if next_card is null. It does not mention any hidden side effects like scheduling changes, but the provided behavior is transparent enough for normal use. Annotations show no destructive or read-only flags, consistent with the described recording action.

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 given the amount of grading detail it conveys. It is well-structured with clear sentences for the rating scale and the miss behavior. While slightly verbose, it does not waste words and each sentence adds value to the user's understanding.

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 provides sufficient context for executing a review: the grading rubric, the follow-up action (asking next card's front), and the termination condition (null next_card). It does not explain error handling or edge cases, but for the core use case it is complete. The absence of an explicit output schema in the provided definition is mitigated by the description's mention of 'next_card'.

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 the 'rating' parameter is described in detail (1=Again, 2=Hard, 3=Good, 4=Easy). The 'session_id' and 'card_id' parameters have no description in the schema or the description text, leaving their purpose and expected values ambiguous. With schema coverage at 33%, the description fails to compensate for the missing details on the other two parameters.

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

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

The description clearly states the tool's primary action ('Record the user's result on a card and get the next one') and specifies the resource (card) and outcome (next card). It distinguishes itself from sibling tools by focusing on review submission rather than creation, deletion, or 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 provides explicit grading criteria and rating definitions, giving clear instructions on how to grade responses. It also specifies what to do on a miss (state the exact answer) and how to handle the next card. However, it does not explicitly contrast with alternative tools like show_answer or end_session, though the purpose is implicit.

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

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

The description does not disclose side effects such as whether review history is preserved, whether the card is fully replaced, or any impacts on scheduling or progress. The annotations indicate idempotent and non-destructive, but the description itself adds no behavioral detail beyond the verb 'rewrite'.

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—a single sentence with no extraneous detail. It follows a clear verb-resource structure and is easy to parse.

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

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

The description is too brief to convey important context such as required parameters (all three are required), potential error conditions, or behavior when the card does not exist. It also does not clarify that both front and back must be provided; the schema indicates this but the description leaves it 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?

The description mentions 'front and back text' which maps to the front and back parameters, but it does not explain the card_id parameter or that it is required for identifying the target card. The schema has no per-field descriptions, so the description provides minimal additional semantic value.

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

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

The description clearly states the action (rewrite) and the resource (a card's front and back text). It is specific enough to distinguish from creating or deleting cards, though it omits explicit mention of the card_id identifier, which is implied by 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?

No guidance is provided about when to use this tool versus the sibling tools (e.g., create_cards, delete_card). There is no mention of prerequisites, caution, or context that would help an agent decide to invoke this over alternatives.

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