Flash

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

Annotations cover the safety profile (destructiveHint=false, idempotentHint=true), and the description adds high-value context beyond them: nothing is deleted, no confirmation is needed, subdecks are affected, and cards can still be added by name. This is exactly the extra behavioral detail an agent needs.

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 front-loaded sentences with zero waste; each adds a distinct, useful fact (when to use, what happens, reversibility/confirmation) without redundancy.

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

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

For a single-param tool with an output schema and full annotations, the description covers the state transition, side effects, reversibility, and confirmation expectations, leaving no ambiguity about calling it correctly.

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

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

Schema coverage is 100%, so the schema already fully documents the single 'deck' parameter including its full-name format and the list_decks pointer. The description adds no parameter-specific syntax or format details, so the baseline 3 is appropriate.

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

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

States a specific verb (archive) and resource (deck), and precisely describes the state transition: deck leaves the study queue and due counts while cards and history are preserved. This clearly distinguishes it from delete_deck and from unarchive_deck.

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 gives the when-to-use condition ('user is done with a deck (an exam passed) but wants to keep it'), names the reverse tool (unarchive_deck), and even notes a consequent behavior (start_study_session finds nothing). Nothing is left to inference.

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

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

Annotations already declare this is a non-read-only but non-destructive, closed-world mutation. The description adds real behavioral context beyond them: the effect is scoped to today only, calls are cumulative ('each call adds more'), there is a 500 cap, and the return value is the total extra granted today. It does not state auth/permission requirements, which keeps it short of a 5.

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 tight sentences, front-loaded with the trigger condition and scope, then the alternative. No filler and nothing repeated from structured fields.

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

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

For a two-parameter additive mutation with an output schema and full annotation coverage, the description covers trigger, scope, cumulative behavior, cap, return value, and the alternative tool. 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 coverage is 100%, so baseline is 3. The description nonetheless reinforces the semantics an agent could misread from a default of null: omitting 'deck' boosts the account-wide allowance rather than a specific deck, and it restates the 500 ceiling on 'extra'.

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

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

States a specific verb+resource ('adds extra new cards for today') with the exact scope (today only, per-deck or account-wide) and names the sibling it is not (set_limits). An agent can distinguish it from set_limits and create_cards without opening any schema.

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

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

Explicit trigger condition is given ('when the user wants more new cards today than the daily limit allows'), reinforced by a concrete user utterance example, plus an explicit alternative ('To change the limit for every day, use set_limits'). Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the bar is lower, yet the description still adds real behavioral context: the deck is created if missing, parent decks are created for Parent::Child, cards enter spaced-repetition scheduling, and the batch size is capped at 1-500. It stops short of stating what happens on partial failure against that cap or whether the operation is atomic/idempotent.

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 first sentence is long and run-on but front-loads the trigger condition, and the remaining clauses (deck creation, scheduling, cloze syntax, media path, alternative tool) each carry distinct information. Every sentence earns its place, though the opening could be split for faster scanning.

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, return values need not be explained, and the description covers the remaining agent-relevant context: creation trigger, deck auto-creation with parents, batch limits, scheduling behavior, and the alternative mutation tool. Nothing an agent needs in order to call this 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 description coverage is 100% and the field descriptions are unusually rich, so the baseline is 3. The description adds only marginal meaning — cloze syntax {{c1::answer}} (already in note_type) and the /media/{id} media convention (not in the schema) — while most of the field-level semantics, including the very detailed speech-block rules, live in 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 a specific verb+resource ("Saves 1-500 cards into one deck of their Flash account") and names the exact scope (1-500 cards, one deck, created if missing). It also explicitly names the sibling it is not — "To change existing cards use update_cards, not new copies" — so an agent can separate it from update_cards without opening either schema.

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

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

It gives a clear when-to-use trigger ("Use this when the user wants flashcards") with enumerated input sources (notes, slides, a shared file, a named topic, this conversation) and the goal (memorize and review later). It names the alternative for the mutation case (update_cards) with the condition that selects it.

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

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

Annotations cover only the safety profile (readOnlyHint=false, destructiveHint=false); the description goes well beyond by disclosing that missing parents are auto-created, that Parent::Child syntax creates subdecks, and that creation is refused on duplicate names. These are non-obvious behaviors an agent must know before calling.

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 sentence-fragments, all front-loaded: purpose, then naming/subdeck mechanics, then the create_cards exclusion, then goal_date, then the refusal condition. No filler and nothing redundant.

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

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

An output schema exists so return values need no explanation. The description covers the failure mode (duplicate refusal), the naming convention, parent auto-creation, and the goal_date trigger, which is everything needed to invoke this tool confidently.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds actionable naming syntax (Parent::Child) and the conditional rule for goal_date ('when the user is studying for a date... pass goal_date') that an agent must apply at selection time. It does not add anything for languages or description, keeping it short of a 5.

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

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

States a specific verb+resource ('Creates a new deck') and immediately disambiguates from the sibling create_cards ('Not needed before adding cards, since create_cards creates its deck'). Also distinguishes its subdeck/parent-creation capability, which no other sibling offers.

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

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

Explicit when-to-use ('when the user asks for an empty deck to fill later, or to set up a structure of decks'), explicit when-not ('Not needed before adding cards'), and names the alternative tool. Also gives a conditional rule for goal_date.

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

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

Annotations declare destructiveHint=true, and the description goes well beyond that with the two-phase confirmation protocol: first call deletes nothing, returns the set plus a confirm_token, tokens last ten minutes, survive reconnects, and completed retries return their original result. This is exactly the idempotency and safety context an agent needs for a destructive batch operation.

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

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

Four dense sentences, all front-loaded: purpose first, then the confirmation mechanics, then sibling routing. Every sentence carries unique operational information and none is wasted.

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

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

An output schema exists so return formatting needn't be explained, yet the description still usefully notes what the first call returns (the exact set and confirm_token). Combined with the token lifetime and retry semantics, an agent has everything needed to call this 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 coverage is 100% and correctly describes both parameters, so the baseline is 3. The description adds procedural meaning the schema lacks: the two calls must carry the same card_ids, and confirm_token must be passed back only after the user confirms once for the batch.

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

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

States a specific verb and resource ('delete specific cards') and explicitly distinguishes itself from siblings delete_deck and archive_deck. An agent can route correctly without opening any schema.

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

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

The first sentence gives the when ('user asks to delete specific cards') and the last names the alternatives with their selecting conditions: delete_deck for a whole deck, archive_deck to stop studying but keep it. Nothing is left to inference.

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

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

Goes well past the destructiveHint=true annotation with the actual mechanics: the first call deletes nothing, returns decks_affected plus card IDs/count and a confirm_token, tokens expire in ten minutes and survive reconnects, and a changed subdeck invalidates confirmation. This is exactly the kind of operational detail annotations cannot convey.

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?

Five tight sentences, front-loaded with the destructive scope before the fallback alternative. No filler or restated title 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?

Despite an output schema existing, the description still names the salient return fields (decks_affected, card IDs and count, confirm_token), and the two-phase confirmation workflow is fully specified. Nothing an agent needs to call this 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 coverage is 100%, so the baseline is 3, but the description adds real meaning to confirm_token: it must come from the first call, be passed back after user confirmation, and it expires. The deck parameter is left to the schema, which already covers it adequately.

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

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

States a specific verb and resource with explicit scope: 'permanently delete a whole deck, every subdeck under it and all their cards.' An agent can distinguish it from sibling archive_deck without opening either schema.

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

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

Gives the trigger condition ('when the user asks to permanently delete a whole deck') and names the alternative alongside its selecting condition: 'To keep the cards but stop studying them, use archive_deck.'

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 idempotentHint=true and destructiveHint=false, and the description reinforces this concretely: 'Every review already recorded stays, and ending a session again changes nothing.' That adds specificity about persistence and repeat-call behavior beyond the bare hint, though it largely restates what the 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?

Three sentences, front-loaded with the usage condition followed by effects and the recap instruction; nothing is wasted. It is slightly longer than the tool's simplicity demands, and the idempotency sentence partly overlaps the annotations.

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

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

With an output schema present, the return values need not be detailed, and the description still names them briefly. Usage condition, side effects, and idempotency behavior are all covered for a one-parameter session-ending tool with full 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?

Schema description coverage is 100% and the single session_id parameter is documented as the value start_study_session returned. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies for a fully documented single-parameter schema.

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

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

States a specific verb and resource ('Closes the session') and its scope, plus what it returns ('its summary (cards reviewed, counts by rating)'). An agent can distinguish it from siblings like start_study_session, submit_review, and panel_grade without opening a 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?

'Use this when the user wants to stop studying before the cards run out, or after the last card' gives an explicit triggering condition covering both natural end states. No alternative tool is named for comparison, and no when-not case is given, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, non-destructive, closed-world, so the safety profile is covered. The description adds useful semantics beyond that: the 'null = inherits' encoding for deck overrides and the fact that values reflect remaining capacity for today, which an agent wouldn't infer from annotations alone.

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

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

Two sentences, front-loaded with the trigger and then the payload. The second sentence is dense but every clause (defaults, extra cards, overrides, null=inherits, remaining counts) earns its place; slightly long single sentence but well organized.

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?

Complete enough for a zero-arg read tool with an output schema: trigger, scope (today), and the shape of the result are all described. Since an output schema exists, it needn't detail exact field names, and it doesn't over-promise.

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

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

Zero parameters, so the baseline is 4; the description correctly implies no input is needed beyond the implicit 'today' scope. Nothing to document, and it doesn't waste words on 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?

States a specific verb+resource (shows today's study limits) and enumerates exactly what is returned: account defaults and per-deck overrides with remaining new/due counts. Clearly distinct from the mutating sibling set_limits.

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?

Opens with explicit trigger conditions: 'when the user asks how many new cards or reviews they get per day, or why a session stopped while cards remain.' That is clear context for when to invoke. It doesn't explicitly name set_limits as the write counterpart or state exclusions, so it stops short of a 5.

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

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

Annotations already cover the read-only/non-destructive profile, yet the description adds substantial behavior: newest-first ordering, authenticated media URLs requiring a Bearer token GET (never speak URLs or markup), sources exposing cloze answers, shared-source edits propagating to sibling_card_ids, and pagination mechanics. This is well beyond what the structured fields convey.

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?

Dense and front-loaded, with the usage trigger first and pagination/auth/domain caveats after. Every clause carries information, though the single long paragraph is heavier than strictly necessary.

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

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

Despite the schema and output schema already existing, the description supplies everything an agent needs to call and consume the result correctly: filtering, ordering, media auth, source/cloze semantics, sibling propagation, and pagination termination. Nothing material is left to 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?

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond it: 'by deck or search text' clarifies the two filters combine as selectors, and 'Page with next_cursor as before_card_id while has_more; trust has_more, not the count' explains the cursor's role and the correct loop-termination signal.

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

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

States a specific verb+resource ('see, find or check their cards'), scopes the return ('whole cards and editable sources, newest first, by deck or search text'), and explicitly distinguishes itself from update_cards, delete_cards and start_study_session. An agent can route to it without opening the schema.

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

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

Gives explicit when-to-use ('when the user wants to see, find or check their cards') and a prerequisite ordering ('before update_cards or delete_cards'), plus a routing rule away to start_study_session for quizzing. Alternatives and conditions are named, not implied.

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

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

Beyond the readOnly/non-destructive annotations, it discloses non-obvious domain behavior: deck names are paths, subdecks are nested and listed after their parent, parent counts already include subdecks (so rows must not be summed), and archived decks appear with archived: true and zero counts. These are exactly the traits an agent could otherwise get wrong.

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

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

Four short sentences, front-loaded with the trigger condition, then the aggregation caveat and archived-deck behavior. Every sentence carries distinct information with no restatement of the name or title.

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

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

For a zero-parameter list tool with an output schema and read-only annotations, nothing essential is missing: usage trigger, hierarchy semantics, the double-counting trap, and archived-deck handling are all covered.

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

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

The tool takes no parameters, so the baseline is 4. The description's path and count-inclusion notes concern output semantics rather than inputs, and an output schema already exists, so no additional parameter meaning is required.

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

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

States a specific verb and resource (lists decks) and immediately scopes what each row contains (due and new card counts). It is clearly distinguishable from siblings like list_cards or list_tags, so an agent can pick it without opening the schema.

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

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

Gives concrete trigger conditions: when the user asks what decks exist or what is due, or before choosing a deck to study or add cards to. It does not name a competing alternative or state when not to use it, which keeps it just short of the top band.

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/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: results include per-tag card counts and cover subdecks of the given deck, which the annotations do not convey.

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

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

Two sentences, no filler, and the practical use case is front-loaded. The ordering puts usage before the actual operation, which is slightly inverted for a tool definition, but nothing is wasted.

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

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

With an output schema present and annotations covering the safety profile, the description supplies everything else an agent needs: when to call it, what it returns conceptually, and the deck scoping semantics. Nothing material is missing.

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

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

Schema description coverage is 100% and the single 'deck' parameter is fully documented there, including path syntax and subdeck behavior. The description's 'one deck (and its subdecks) or across every deck' restates the schema rather than adding format or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb ('Lists') and resource ('the user's tags') plus the aggregation detail (card counts per tag) and scope (one deck with subdecks, or every deck). An agent can distinguish it from list_decks and list_cards at a glance.

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

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

Gives a clear triggering condition ('when the user wants to study one part of their cards, such as a chapter, lesson or exam') and ties it to the downstream need of narrowing start_study_session. It does not state when NOT to use it or name a competing sibling, so it falls short of the top bar.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true; the description corroborates rather than contradicts these by framing the write as reversible (Undo restores the card) and by disclosing the return behavior ('the panel's next card'). It adds real context about call-site and reversibility, though not permissions or failure modes.

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

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

A single dense sentence with the critical constraint ('never call it yourself') front-loaded, then the card state change, then the return value. Every clause 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?

An output schema exists so return values need not be enumerated, and all three parameters are fully described in the schema. For a panel-internal mutation tool, the description supplies all the context an agent needs, including the decisive instruction not to invoke it directly.

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% (card_id, archived, session_id each documented, including the true/false semantics of archived). The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('takes the card on screen out of study', 'puts it back on Undo') and scopes it to the study panel's on-screen card, which implicitly separates it from deck-level siblings like archive_deck and from delete_cards.

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

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

Gives an unusually explicit usage boundary ('Used by Flash's study panel only; never call it yourself') plus the triggering condition (user tapped Archive / Undo). It does not name an alternative tool for agents who need a similar archive operation, so it stops just short of 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious context: this is a panel-internal paging call that returns 'both sides' of the cards. It doesn't describe pagination limits or termination behavior, but the added scope context is real.

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

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

A single sentence that front-loads the most important constraint (never call it yourself) before describing the return. Zero wasted words.

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

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

For a one-parameter, panel-internal tool with an output schema and full schema coverage, the description supplies everything an agent needs: who may call it, what it returns, and which sibling to use instead.

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

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

Schema description coverage is 100%, with the single card_ids parameter documented as 'Up to 20 of the card_ids the panel was given.' The description implies those ids come from the panel's paging context but adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource — 'Returns more of the cards the panel is paging through' — and explicitly contrasts it with the sibling list_cards. An agent can distinguish it from the other card-listing tools without opening a 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?

Explicit when/when-not guidance: 'Used by Flash's panel only; never call it yourself (use list_cards).' Names the correct alternative and the exclusion condition outright, leaving nothing to inference.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-derivable context: the tool is reserved for the panel's quick-edit flow, must not be invoked by an agent, and returns a narrow two-field projection rather than the full card.

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 short sentences with zero filler, and the critical do-not-call warning is front-loaded before the description of the return value. Every clause 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?

With an output schema present, the description needn't document return values, and it correctly avoids doing so. For a single-parameter, panel-internal read tool, the callability warning plus the field-projection note is sufficient for an agent to decide correctly (i.e., not to call it).

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

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

Schema description coverage is 100%, and the schema's card_id description ('the card whose answer to show: the card_id of the front just asked') is richer than anything in the tool description. The description adds no syntax, format, or edge-case meaning beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb+resource (returns the fields behind a card) and names its domain ('Flash's study panel only'), which differentiates it from general read tools. However, 'the two fields' is left undefined and the description leans on an access constraint rather than a crisp statement of what the tool produces.

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 states an explicit prohibition ('never call it yourself') and names the correct alternative ('use list_cards'), which is exactly the when-not/alternative guidance an agent needs. Nothing about selection is left to inference.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description usefully adds that the call returns the panel's next card and is reserved for the panel UI. It does not address the mildly non-obvious idempotentHint=true on a grade-recording write, nor failure behavior, so it falls short of full disclosure.

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

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

A single sentence with zero waste; the critical restriction is front-loaded before the alternative. Every clause 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 5-param mutation tool with an output schema and full annotation coverage, the description supplies what structured fields cannot: who may call it and what the call returns. Only failure/error semantics are left unstated, which is a minor gap.

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

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

Schema description coverage is 100%, including the rating scale (1=Again…4=Easy) and the meaning of answer_ms and ui_locale, so the schema carries the parameter burden. The description only loosely refers to 'the grade the user tapped' and adds no syntax or format detail beyond the schema.

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

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

States a specific verb + resource ('Records the grade the user tapped') and adds a second behavior ('returns the panel's next card'), and explicitly positions itself against the sibling submit_review. An agent can distinguish it from other write tools without opening a schema.

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

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

Gives an explicit when-not ('never call it yourself') plus the named alternative ('use submit_review'), which is exactly the routing information an agent needs. This is a rare case where both the exclusion and the substitute are stated.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds that it is user-initiated from the panel ('after the user tapped the panel's offer') and is not for the agent to call directly. It does not detail side effects or permissions, but that is less critical given the annotations and output schema.

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

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

Two tightly written sentences. The most important directive ('never call it yourself') is front-loaded, followed by the behavior. Nothing is wasted.

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

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

For a panel-only mutation tool with full schema coverage, annotations, and an output schema, the description provides enough context: who should call it, when, and what it does. No return-value explanation is needed because the output schema exists.

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 only parameter (timezone) is fully described in the schema with an IANA example. The description does not add any parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb ('Turns on reminders') and the resource (reminders tied to due cards), and explicitly scopes it to Flash's study panel. This distinguishes it from sibling tools such as start_study_session and set_limits, which are not panel-only.

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 'Used by Flash's study panel only; never call it yourself' and gives the triggering condition 'after the user tapped the panel's offer.' This is a clear when-to-use and when-not-to-use directive, leaving no ambiguity for the agent.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and repeat-call behavior are covered structurally. The description adds useful scope context ('a card's two fields') and caller restriction, but says nothing about how next_card_id affects the mutation or what happens to fields not supplied.

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

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

Two short sentences with the caller restriction and alternative front-loaded, followed by the effect. No filler or repetition.

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

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

An output schema exists, so the return value needn't be re-explained, and annotations carry the safety profile. The remainder is largely complete, with only the semantics of next_card_id left thinner than ideal for a 4-parameter mutation.

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 75%, so most parameters are already documented in the schema. The description adds only that the two fields are the quick edit's front/back values and doesn't clarify next_card_id's role, so it does not meaningfully exceed the schema baseline.

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

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

States a specific verb and resource ('Saves the panel's quick edit of a card's two fields and returns the card as it now reads') and explicitly names the sibling alternative (update_cards). An agent can distinguish this from update_cards and panel_edit_source without opening any schema.

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

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

Gives an explicit when-not-to-use rule ('never call it yourself') plus the correct alternative ('use update_cards') and a positive condition ('Used by Flash's study panel only'). Routing is unambiguous.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: the tool is an internal panel-only endpoint, which is a behavioral constraint no annotation expresses. It does not cover return shape or latency, but the output schema carries returns.

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 short sentences, zero waste, with the caller restriction front-loaded ahead of the return description. Every clause carries information an agent needs.

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?

An output schema exists, so return values need not be explained. Given that, the description covers the only non-obvious thing about this tool: who is allowed to invoke it and what to call instead.

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 card_id is fully documented there ('the card_id of the front just asked'), so the schema does the heavy lifting. The description adds no parameter syntax or semantics beyond that, making the baseline 3 correct.

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

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

States a specific verb and resource ('Returns a card's back') and immediately scopes it to the study panel, which is exactly what distinguishes it from the sibling show_answer. An agent can route between the two without opening either schema.

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

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

Explicitly says 'never call it yourself' and names the alternative to use instead ('use show_answer'). This is a rare case of a tool that positively documents when NOT to call it, with the substitute named.

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

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

With annotations already covering the safety profile (readOnlyHint false, idempotentHint true, destructiveHint false), the description adds substantive behavior: subdecks, cards and review history follow the move; intermediate decks are created if missing; operations are refused rather than merged, and moving a deck inside itself is blocked. These side effects and failure modes go well beyond the structured fields.

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

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

Front-loaded with the trigger, then path semantics with a concrete example, then refusal conditions. Every sentence carries distinct information 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?

An output schema exists, so return values need not be explained. The description covers the operation, path semantics, side effects, and failure modes, leaving nothing an agent needs in order to invoke it correctly.

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

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

Schema coverage is 100% and both parameters already document the '::' path format, so the baseline is 3. The description adds the non-obvious detail that an intermediate target path is 'created if missing', which the schema does not state.

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 names a specific verb ('rename') and expands scope precisely to the three real operations: rename, nest under another, or pull to top level. This clearly distinguishes it from siblings like create_deck, archive_deck, and delete_deck without requiring the schema to be opened.

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

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

It gives an explicit trigger ('Use this when the user asks to rename a deck, nest it under another, or pull it out to the top level') and states refusal conditions. It stops short of naming a sibling alternative to use in edge cases, but the when-to-use context is unambiguous.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, but the description adds real substance: a restore rewrites the card's source and its sibling cards in place, schedules and review history are preserved, the replaced text is retained, and restores that would remove cards are refused. This explains exactly why the operation is non-destructive and idempotent, which the annotations alone cannot convey.

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 trigger, then the two-step call pattern, then the behavioral consequences. Every sentence carries distinct information, though the 'keeps the text it replaces too' clause near the end slightly echoes the opening sentence.

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, return values need not be explained. The description still covers the trigger, the listing/restore call sequence, the in-place rewrite scope including siblings, and the refusal condition, which is everything an agent needs to invoke this tool safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond it by specifying the ordering of the listing ('newest first') and the confirm-with-user step between the two calls, which the schema does not state. It also mirrors the schema's note that a version covers sibling cards, so the marginal gain is real but modest.

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+resource (restore an earlier version of a card) and immediately distinguishes the action from ordinary editing by explaining that every edit retains the replaced text. An agent can tell this apart from update_cards, delete_cards, or archive_deck without opening the schema.

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

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

It gives a concrete trigger ('user wants an earlier version of a card back, for example after an edit they did not want') and a full two-phase procedure: call with card_id alone to list, confirm with the user, then call again with revision_id. It does not, however, name the alternative tools (e.g. update_cards) that an agent should choose instead when the user wants a new edit rather than a restore.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=true; the description adds meaningful behavioral context beyond that — omitted fields are left unchanged, -1 clears a deck override so it inherits account defaults, and an empty string clears goal_date. This inheritance/clearing semantics is valuable, though some of it is echoed from the schema text.

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?

Dense but front-loaded: the trigger condition leads, followed by the deck/account branching, clearing semantics and the alternative tool. Slightly long and packs several clauses, but nearly every sentence carries distinct information.

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

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

With an output schema present, return values need no explanation, and the description fully covers the account-default vs deck-override branching, reset semantics, and the sibling alternative. Nothing an agent needs to invoke 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 description coverage is 100%, so the schema already documents every parameter including the -1 and empty-string clearing rules. The description reinforces the deck/goal_date relationship and the clearing behavior but adds little that isn't already in the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (set daily new/review limits, per-deck or account-wide) and immediately distinguishes itself from the sibling boost_new_today for same-day extra cards. An agent can route correctly without opening any schema.

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

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

Explicitly says "Use this when the user wants to change how many new cards or reviews they get per day" and names the alternative (boost_new_today) with its distinguishing condition (extra new cards today only). It also covers the goal_date use case and the no-deck vs with-deck branches.

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 safety profile is covered. The description adds genuinely useful behavior beyond that: 'records nothing' clarifies the call has no scheduling side effect, and it supplies the required follow-up workflow (tell the user, then submit_review rating 1). It does not describe what happens if called outside a session, but the coverage is strong.

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

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

Three tight sentences: trigger, return/behavior, then alternative. Front-loaded with the use condition and no filler; each sentence carries a distinct instruction.

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 single-parameter read tool with an output schema present, the description need not explain return values, yet it briefly does ('returns the card's back'). Combined with the workflow handoff to submit_review, an agent has everything needed to call it correctly.

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

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

Only one parameter with 100% schema description coverage, which already says it is 'the card whose answer to show: the card_id of the front just asked.' The description reinforces the same constraint without adding new syntax or format meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('show the answer', 'card's back') and pins it to a precise moment: the card just asked in a study session. It also names the sibling it is not (list_cards) for the out-of-session case, so an agent can route correctly without opening schemas.

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

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

Explicit triggering conditions ('user gives up', 'asks for its answer'), an explicit exclusion with the alternative ('to read whole cards outside a session, use list_cards'), and a prescribed follow-up action (submit_review with rating 1/Again). Nothing is left to inference.

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

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds substantial context beyond them: progress is attributed only to cards asked in this session and graded via submit_review, grading_mode governs the whole session, and media URLs require the connector Bearer token. It omits session lifecycle (how/when it terminates, cf. end_session), which keeps it just short of the top 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?

Front-loaded with the usage trigger, then mechanics, then rendering rules — a sensible ordering. It is dense with long compound sentences, and the rendering/grading rules could be tightened, but nearly every clause carries actionable 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?

Despite an output schema existing, the description usefully supplements it with what matters for correct behavior: ask the returned first card and wait, honor grading_mode, render front_html for display versus speech, present cloze gaps without revealing answers, and never read raw markup, URLs, or internal fields aloud. Complete for the agent's task regardless of the rich structured metadata.

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

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

Schema description coverage is 100%, so the schema already documents tag, deck, and tags (including Parent::Child syntax and the ten-tag cap). The description restates the scope semantics without adding new format or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Starts a spaced-repetition session over the cards due now') with explicit scope options (all, one deck plus subdecks, or cards carrying every given tag). It actively distinguishes itself from siblings by naming create_cards for card creation and list_tags for tag names, so an agent can route correctly without opening the schema.

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

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

Gives an explicit trigger ('when the user wants to study, review, practice, be quizzed on or drill their flashcards, including cards made moments ago') and routes related intents elsewhere: create_cards for new cards, list_tags for tag names, submit_review for grading. The when-not-to-use boundary is effectively stated.

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

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

Annotations only say it is a non-destructive write; the description adds substantial behavior the annotations cannot carry: scheduling consequences ('sets when the card comes back'), the next_card return and its null-terminates-session semantics, and the required follow-up action of stating the exact answer on a miss.

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 sentence is long but front-loads the usage trigger and keeps the grading rubric in a compact, scannable form. Some of the 1-4 legend restates the schema's own rating description, which is mild redundancy, but the surrounding nuance rules earn their space.

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?

An output schema exists, so return values need no prose explanation, yet the description still covers the one behaviorally critical return detail (null next_card ends the session). Combined with the grading policy and session-flow instructions, nothing an agent needs to invoke this 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 coverage is 100% and the schema already defines the 1-4 rating mapping, so the baseline is 3. The description goes beyond it by supplying a strict grading rubric with concrete edge cases ('60' for '60 to 100 bpm' is 1), which materially changes how an agent picks the rating 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 states a specific verb+resource ('records how well they knew it'), plus two side effects: it 'sets when the card comes back' and 'returns the next card.' This cleanly separates it from siblings like show_answer and start_study_session.

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 states timing precisely ('after the user answers the card just asked in a study session') and describes the hand-off to next_card's front and the session-end condition. It doesn't name a competing tool to avoid, so it stops short of an explicit when-not, but the usage context is unambiguous.

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

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

Annotations cover the safety profile (idempotent, non-destructive, closed-world), but the description adds genuinely non-obvious behavior: archived cards resume with their original review history, overdue cards become due immediately subject to daily limits, and both subdecks and parent decks cascade in the operation. That cascade and scheduling semantics are not derivable from the annotations or schema.

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

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

Front-loads the usage trigger, then covers effects in two compact sentences with no filler. Minor slack in the trailing phrasing ('and so do the decks it sits in'), but nothing that warrants trimming substantively.

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?

An output schema exists, so return values need not be explained. For a one-parameter mutation the description covers the trigger, the scheduling consequence, and the scope of cascading effects, leaving no gap an agent would need filled before calling it.

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 is a single required 'deck' parameter with 100% schema description coverage, including format guidance and a pointer to list_decks. The description adds no parameter-level detail, so the baseline 3 applies since the schema already carries the full burden.

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

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

States a specific verb and resource ('Puts it back into study') and describes the concrete state change: cards regain prior review history and resume scheduling. This is clearly distinguishable from the inverse sibling archive_deck without any schema inspection.

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 opening sentence gives an explicit trigger condition: 'Use this when the user wants to study an archived deck again.' That is a clear when-to-use, but it names no alternative (e.g. archive_deck as the inverse) and states no when-not condition, so it stops short of a 5.

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

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

Annotations already flag idempotentHint and destructiveHint=false, but the description adds crucial mechanics: partial patch semantics (only supplied fields change), atomicity across 1-500 cards, preservation of schedule and review history, undo via restore_cards, note type immutability, and refusal of edits that would remove cards.

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?

Dense but front-loaded: use-case first, then mechanics, then preconditions (read list_cards), then edge rules (no removal, note type stays), then pointer to create_cards. No wasted clauses.

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 nested-patch mutation with an output schema, this description covers selection criteria, partial-update semantics, atomicity, undo path, preconditions, and safety constraints—enough for an agent to invoke correctly without reading other docs.

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 field-level descriptions are rich (CardPatch fields fully described). The description still adds cross-cutting parameter guidance: supply card_id with only fields to change, copy sibling_card_ids from list_cards, and follow create_cards' field notes for HTML/speech fields.

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

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

States a specific verb ('fix, reword, correct or retag'), resource (cards), and scope (1-500 existing cards), and explicitly names what distinguishes it from siblings delete_cards and create_cards.

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 to fix, reword, correct or retag cards they already have'), which sibling to use for removal (delete_cards), how to pre-read with list_cards, and the sibling_card_ids rule for shared sources.

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