Flash

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

Annotations only say readOnlyHint=false and destructiveHint=false, but the description enriches this with concrete side effects: the deck leaves the study queue, due counts are affected, start_study_session finds nothing, subdecks are archived with it, and cards can still be added by name. It also confirms reversibility and that no confirmation is needed because nothing is deleted.

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

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

Four sentences deliver all essential facts in a natural order: action and intent, non-destructive effects, reversal, subdeck behavior, and post-archive addability. There is no filler or redundant restatement of the tool name.

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 fully covers why, what happens, what doesn't happen, how to reverse, and edge behaviors (subdecks and adding cards) for a one-parameter mutation. Given the annotations and output schema, no critical information 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?

With a single parameter whose schema description is 100% covered ('Deck name.'), the schema already carries the parameter meaning. The description's added 'by name' detail is minor and doesn't materially extend the semantic of the deck parameter.

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 and resource ('Archive a deck') and immediately scopes it to decks the user is done with, e.g. after passing an exam. It distinguishes the operation from sibling unarchive_deck by explicitly saying 'unarchive_deck reverses it' and from destructive deletion by stating 'Nothing is deleted.'

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 clear when-to-use guidance ('a deck the user is done with (an exam passed)') and points to the alternative unarchive_deck as the reversal path. It doesn't explicitly contrast with delete_deck or state when archiving is inappropriate, so it stops just short of full when-not coverage.

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?

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 only cover the safe-mutation profile. The description adds real behavioral facts beyond them: atomic creation, the 1-500 card bound, auto-creation of a missing deck including named Parent::Child ancestors, and the media reference convention. These are exactly the traits an agent needs 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?

Front-loaded with purpose and constraints, and every sentence carries operational information. The only slightly soft line is the meta-instruction to 'follow the field notes,' which is generic, but it costs little.

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?

Deck auto-creation, hierarchy syntax, atomicity, card limits, media conventions, and sibling routing are all covered, and an output schema already exists so return values need not be explained. Nothing needed 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 only 50%, so the description must compensate and largely does: it explains deck hierarchy syntax (Parent::Child) for the undocumented deck parameter and gives cloze syntax ({{c1::answer}}) and media handling for the card payload. It stops short of fully documenting the card fields, which the schema itself handles.

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

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

States a specific verb and resource (add flashcards) plus the accepted sources (notes, document, topic, conversation), and explicitly distinguishes itself from update_cards. An agent can tell it apart from every sibling 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 both when-to-use (the user asks for cards, from these sources) and an explicit alternative (use update_cards to fix cards that exist rather than adding copies). The routing condition 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 indicate this is not read-only, so the description doesn't need to restate mutation. It adds useful behavioral detail: decks are created empty, Parent::Child creates parents automatically if missing, and create_cards will create its own deck. This goes beyond the schema and 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, all informative, with the core action first, then naming mechanics, then a practical pointer to an alternative. There is no filler or repetition of schema/annotation information.

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

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

For a simple two-parameter tool with an output schema, the description is complete. It explains key side effects (parent auto-creation), the empty-deck nature, and the relationship to create_cards. The output schema covers return details, so nothing essential 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?

With 0% schema description coverage, the description must explain parameters, and it does for the required 'name' by documenting the Parent::Child delimiter and implicit parent creation. The optional 'description' parameter is not mentioned, but the required parameter is well covered.

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

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

The description clearly states a specific action ('Create a new (empty) deck') and identifies the resource. It also distinguishes itself from the sibling create_cards by noting that create_cards creates its own deck, so there is no ambiguity about what this tool does.

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 the tool is 'Not needed before create_cards, which creates its deck,' giving an explicit when-not-to-use condition and naming the alternative. It also implies use it when you need a standalone empty deck, especially with subdeck naming.

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 destructiveHint=true, and the description adds substantial detail: the first call deletes nothing, tokens expire in ten minutes and survive reconnects, and completed retries return their original result. This is exactly the behavioral context needed 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?

Five short sentences, all carrying essential information. The core action and batch limit are front-loaded, followed by the confirmation protocol and token lifecycle, with no filler.

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

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

For a destructive two-step batch operation, the description covers the complete protocol, safety behavior, token expiration, reconnect survival, and retry semantics. An output schema exists, so omitting return-value details is acceptable.

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

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

Schema description coverage is 0%, but the description compensates fully. It explains card_ids as explicit card IDs in a 1-500 batch and specifies that confirm_token is a returned confirmation token to be resubmitted within ten minutes.

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

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

The description opens with 'Delete 1-500 explicit card IDs,' giving a specific verb, resource, and cardinality. This clearly distinguishes the tool from deck-level siblings like delete_deck and archive_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?

It clearly lays out the intended two-call workflow: first call prepares and returns a token, user approves, then the same card_ids are retried with confirm_token. It does not explicitly name alternative tools, but the card-ID focus and confirmation flow provide clear context.

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

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

Annotations only indicate destructiveHint=true, but the description goes far beyond that by disclosing the two-phase confirmation flow, that the first call performs no deletion, that tokens last ten minutes, that changed data invalidates confirmation, and that completed retries return the original result. This is exemplary behavioral disclosure for a destructive tool.

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

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

Every sentence earns its place: the effect, the confirmation protocol, token lifetime, invalidation conditions, and retry behavior are all covered without repetition. The description is dense but not bloated, and the most important destructive scope is front-loaded.

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

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

Given the tool's destructive complexity and the existence of an output schema, the description is remarkably complete. It explains what the first call returns, how confirmation works, how long tokens last, what invalidates a confirmation, and what retries return. Nothing essential for safe invocation is missing.

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

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

Even though the schema already describes both parameters, the description adds critical semantic meaning: deck is the root of a hierarchy, confirm_token must be omitted on the first call and echoed back after confirmation. This protocol-level guidance materially helps an agent invoke the tool correctly.

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

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

The description uses a specific verb and resource: 'Permanently delete a deck, every subdeck under it (Parent::Child names) and all their cards.' This clearly distinguishes the tool from siblings like delete_cards or archive_deck by scope and permanence. It leaves no ambiguity about what operation the tool performs.

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 call pattern: first call without a token, then repeat with the returned confirm_token after user confirmation. It implicitly distinguishes this hierarchy-level deletion from individual-card deletion, though it does not explicitly name alternatives such as delete_cards or 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?

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 mark it read-only and non-destructive, and the description adds substantial operational context: authenticated media URL retrieval with the same Bearer token, an instruction not to speak URLs or markup, a warning that sources contain cloze answers, a note that shared source edits affect sibling_card_ids, and pagination behavior. This is well beyond what the annotations provide.

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 dense but front-loads the core purpose and then packs pagination, media auth, and cloze caveats efficiently. Every sentence carries relevant information, though the semicolon-heavy style is slightly hard 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?

An output schema exists, so return values need not be explained. For a list tool with pagination, media authentication, and cloze-answer considerations, the description covers the necessary behavioral and parameter context without obvious gaps.

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

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

Schema coverage is 50%, with 'deck' and 'search' described in the schema but 'limit' and 'before_card_id' left undocumented there. The description compensates by explaining limit defaults and maximums and by linking before_card_id to next_cursor/has_more pagination, though it could state before_card_id's role more directly.

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 ('Read') and resource ('complete cards and editable sources') with scope details (formatting, authenticated media URLs). It explicitly routes quizzing use cases to study tools, making it distinguishable from siblings like show_answer and panel_grade.

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

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

Provides clear context for when to use it versus study tools ('use study tools when quizzing') and notes the Bearer token requirement for media URLs. However, it doesn't name specific alternative tools for listing or filtering, leaving some routing inference to the agent.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false), so the safety bar is covered. The description adds real behavioral context beyond them: the 'Parent::Child' path naming convention, the ordering rule that each deck is followed by its subdecks, and that archived decks remain in place with archived: true and zero counts.

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

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

Three sentences, each carrying distinct information: what is returned, the naming/hierarchy convention, and the aggregation warning plus archived-deck handling. The core purpose is front-loaded and no sentence is padding.

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

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

An output schema exists, so return-value documentation is not required, yet the description covers the non-obvious semantics an agent needs (path-based names, subdecks included in parent counts, archived deck representation). Nothing essential for correct invocation or interpretation 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?

The tool takes zero parameters, so there is nothing to document beyond the baseline. The description instead spends its words on output semantics, which is the right tradeoff for a no-arg 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?

States a specific verb and resource ('List the user's decks') plus the payload it returns ('due and new card counts'), which is materially different from the sibling listers list_cards and list_tags. An agent can identify the right tool 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?

Usage is implied rather than stated: it is the enumeration tool for decks, and the warning 'never add rows up' guides interpretation of results. However, it never states when to prefer this over alternatives like list_cards or when-not to call it, so there is no explicit alternative routing.

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 read-only safety profile is covered. The description adds useful behavioral context beyond that: it reports card counts per tag and explains the scoping behavior (one deck and subdecks vs. every deck), which is meaningful for invocation expectations.

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

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

The description is two sentences with no filler. The first sentence front-loads the core purpose and scope, and the second adds a practical usage pointer. 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 simple read-only tool with one optional parameter, an output schema, and annotations already covering safety, the description is complete. It covers scope, the omitted-deck behavior, and the typical use case, so an agent has enough to select and call 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?

Schema description coverage is 100% and the deck parameter is already documented with its path format ('Parent::Child') and omission behavior. The description restates the scoping concept but doesn't add new semantic details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('List the user's tags'), the resource (tags), and the distinguishing detail (card counts per tag). It also specifies the two scope modes (one deck with subdecks, or every deck), which separates it from siblings like list_cards and list_decks.

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

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

The description gives a concrete downstream use case—using tag names as start_study_session's tags to study a portion of a deck—which helps the agent know when this tool is relevant. It does not explicitly mention when not to use it or name a direct alternative for the same outcome, so it falls just short of the highest 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a behavioral constraint annotations cannot express: this tool is reserved for the panel and must not be invoked by the agent. It does not discuss return shape, but an output schema exists to carry 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?

Two compact clauses with zero filler, and the critical constraint ('never call it yourself') is front-loaded ahead of the return behavior.

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

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

With one well-documented parameter, full annotations, and an output schema, the only missing piece would be the invocation constraint — which the description supplies explicitly. Nothing an agent needs to avoid misusing this tool is absent.

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 parameter is fully documented in the schema ('Up to 20 of the card_ids the panel was given'). The description's 'both sides' hints at how the input window maps to output but adds no syntax or format detail beyond the schema, 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?

The description states a specific action (returns more of the cards the panel is paging through) and explicitly names the sibling it is not (list_cards), so an agent can distinguish it without opening the schema. The resource phrasing ('cards the panel is paging through, both sides') is slightly indirect but still conveys the paging-window semantics.

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 when-not ('never call it yourself') and names the alternative to use instead ('use list_cards'), plus the only legitimate caller (Flash's panel). This is exactly the routing guidance an agent needs.

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 mutation/safety profile is covered. The description adds meaningful context that this path exists for Flash's study panel only and that it returns the next card, but with an output schema present that return behavior is partly redundant.

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 economical clauses with zero padding, and the most decisive information (never call it yourself) is front-loaded. Nothing is wasted, though the sentence carries multiple jobs.

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

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

For a tool the agent is told not to invoke, the description covers the essentials: who calls it, why not you, and what to use instead. The return value is covered by the existing output schema. The only real gap is the undocumented card_id/session_id parameters.

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

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

Schema description coverage is only 33% – only 'rating' is documented ('1=Again 2=Hard 3=Good 4=Easy'), while card_id and session_id carry no meaning in schema or description. The description offers no compensating parameter guidance, so an agent relying on prose gains nothing here.

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 ('Records the grade the user tapped') plus its return ('the panel's next card'), and explicitly distinguishes itself from submit_review. Clear enough for an agent to know what it does, though the statement leans on exclusion rather than elaboration.

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-not guidance ('never call it yourself') and a named alternative ('use submit_review'). This is as unambiguous as usage guidance gets, 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 cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower, and the description contributes the non-obvious constraint that this tool is reserved for the internal panel and should not be invoked directly. It does not add rate limits or error behavior, but the output schema covers return shape.

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 filler, with the routing constraint front-loaded before the behavioral clause. Every phrase carries 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?

An output schema exists, so return values need no explanation, and annotations cover safety. The remaining need for a single-param read tool is correct routing, which is fully addressed; only the card_id semantics are left 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?

One parameter with 0% schema description coverage, so the schema does not explain card_id; the description mentions 'a card's back' but never clarifies the id's meaning or source. The name card_id is largely self-evident, yielding a minimum-viable 3 rather than a full compensation.

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

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

The description gives a concrete verb and resource ('Returns a card's back') and clearly marks itself as the panel-scoped variant distinct from the general sibling. It stops short of a 5 only because the actual output/behavior is stated in a single terse clause rather than fully characterized.

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 caller restriction ('Used by Flash's study panel only; never call it yourself') plus a named alternative ('use show_answer') that resolves the ambiguity for a generic agent. Both when-to-use and when-not-to-use are stated directly.

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

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

The description discloses that subdecks, cards, and review history follow the deck to the new location, which is a key consequence. It also states that missing parent decks are created, and that duplicate names cause refusal rather than merge. This goes well beyond annotations, which only say readOnlyHint=false and destructiveHint=false, but don't specify mutation behavior.

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

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

Four sentences, each carrying necessary information, with the primary purpose front-loaded and edge cases after. No redundant wording.

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

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

With an output schema present and clear annotations, the description does not need to cover return values. It covers all relevant execution details: path semantics, creation of parent, following subdecks, refusal conditions, and top-level behavior.

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

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

The schema already covers both parameters at 100% coverage, but the description adds that new_name is a full path and that an intermediate parent is created if missing, which is not in the schema. This extra semantic clarifies the effect of the new_name 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 uses a specific verb ('Rename') and resource ('deck') and explicitly covers both rename and move operations. It distinguishes from siblings like delete_deck, archive_deck, and create_deck by stating the action and usage scenarios. The refusal conditions further clarify its scope (no merging, no self-nesting).

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 starts with 'Use when the user asks to rename a deck, nest it under another, or pull it out to the top level', giving explicit trigger conditions. The 'Refused if' sentence adds when-not constraints, though it doesn't name alternative tools. This is clear context without explicit alternative references, sufficient for an agent to decide.

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

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

Annotations already 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by explaining the intended interaction flow: read the answer aloud and then call submit_review with rating 1. This goes beyond the structured annotations without contradicting them.

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

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

The description is a single, front-loaded sentence that states the core action first, followed by the usage trigger and follow-up instruction. Every clause earns its place, and there is no redundancy or filler.

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

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

For a simple one-parameter tool with a single obvious input and an output schema, the description covers what the tool does, when to use it, and what to do after. The presence of an output schema means return format documentation is handled elsewhere, so nothing essential 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 0%, so the description carries the burden of explaining the parameter. However, it does not explicitly define card_id or its format, relying on the tool name and the phrase "a card's back" to imply it identifies the card. This is insufficient compensation for the missing schema documentation.

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

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

The description uses a specific verb and resource: "Get a card's back (the answer)." This clearly differentiates the tool from siblings like list_cards or submit_review. It also gives an immediate usage context, making the tool's role obvious.

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

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

The description explicitly states when to use the tool: "Use when the user gives up or asks for the answer." It also prescribes the follow-up action with submit_review. It does not mention when not to use it or name alternatives, but the trigger condition 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?

Beyond the annotations, the description discloses important behaviors: it returns the first card front, the due count, and grading_mode; tells the agent to render or interpret front_html, present cloze gaps without revealing answers, and fetch media URLs with the Bearer token. This is rich, actionable behavioral context that the annotations alone do not provide.

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 key trigger conditions and then moves from parameter guidance to output handling. It is longer than necessary, but nearly every sentence carries operational value, and the structure groups related guidance logically.

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, the description still covers the critical runtime behaviors: how to present the first card, how to count due cards, how to follow grading_mode, how to handle media, and what not to read aloud. An agent has enough context to invoke the tool and handle its result 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 input schema already covers all three parameters at 100% coverage, so the baseline is 3. The description adds value by clarifying that tags must all match, that names come from list_tags, and that tags can narrow a deck, which goes beyond the individual schema descriptions.

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

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

The description clearly states the action ('Start a study session') and expands it with a precise list of triggering user intents: study, review, practice, quiz, test, or drill cards. This makes it unambiguous and distinct from sibling tools like end_session or list_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?

It explicitly says the tool is REQUIRED for a defined set of user requests, and even warns not to quiz from memory because only sessions record progress. It also explains how to narrow the session using deck, tags, or both, giving clear decision guidance.

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

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

Annotations are thin (only title and false hints), so the description carries the behavioral burden and does so thoroughly. Beyond the 'Record' mutation implied by readOnlyHint=false, it discloses the return behavior (next_card, null ends session), the requirement to state the exact answer on a miss, and the semantic quirk that 2, 3, and 4 all count as 'knew it.' No contradiction with annotations.

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

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

The description is long (~150 words) but every sentence earns its place: the grading rubric is essential for correct invocation and would be dangerous to compress. The core purpose is front-loaded, followed by grading details in logical order. Minor redundancy exists (the 'only phrasing may differ' point is restated via the bpm example) 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?

For a tool with this grading complexity, the description is nearly complete: it specifies all rating semantics, the miss-handling protocol, and session termination. Since an output schema exists, it need not detail the return structure, though mentioning next_card bridges nicely. A small gap is the lack of explicit words on what session_id and card_id refer to, but the names plus narrative cover 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 only 33% (rating has a one-line enum-like description; session_id and card_id have none). The description compensates substantially for rating, defining each level with precise criteria ('the whole answer, but slowly or unsurely' for Hard) and giving a concrete partial-answer example. It does not touch session_id/card_id, but their meanings are self-evident from names and workflow context.

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

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

The description opens with a specific verb+resource pair: 'Record the user's result on a card and get the next one.' This clearly distinguishes it from siblings like show_answer (which merely displays the answer), start_study_session, and end_session. The exhaustive grading rubric further pins down exactly what the tool does.

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 establishes unambiguous context: it is used during an active study flow when the user has just answered a card, and it elaborates on how to handle each scenario (miss, unsure, easy, null next_card, wrap-up). It does not explicitly name alternatives or state when not to use it, but the placement in the workflow is unmistakable.

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

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

Beyond the annotations, the description discloses meaningful behavioral details: review history is preserved, due reviews become due 'within the daily limits,' subdecks are restored, and parent decks are also brought back. This goes well beyond what readOnlyHint and destructiveHint provide and helps the agent understand side effects accurately.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds a relevant behavioral detail. It is concise without being terse or wasting 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 single-parameter tool with an output schema and rich annotations, the description covers the operation, side effects on reviews, subdecks, parent decks, and daily limits. No critical information is missing for an agent 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?

The schema already documents the only parameter 'deck' with 100% coverage. The description does not add additional parameter-level detail, but the schema is sufficient, so the baseline score of 3 applies.

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

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

The description uses a specific verb and resource: 'Put an archived deck back into study.' It clearly communicates the action and is distinguishable from its sibling archive_deck, which performs the opposite operation.

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

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

The description implies the tool should be used when a user wants to restore an archived deck to active study, and it explains the behavioral consequences. However, it does not explicitly state when not to use it or name alternative tools like archive_deck as the reverse operation.

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

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

Annotations already declare non-read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: atomic batched application, omitted fields staying intact, sibling propagation with retained history, preserved note type, rejection of card-removing edits, and the 1-500 bound.

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 operation and batch bound, then proceeds clause by clause through parameters, prerequisite, shared-source handling, and the delete alternative. Every sentence carries an actionable constraint; there is no filler or restated annotation.

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 annotations covering the safety profile and an output schema covering returns, the remaining burden is constraints and workflows, which the description fully supplies: atomicity, partial-update semantics, sibling propagation, removal rejection, and the sibling_card_ids requirement. Nothing needed 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 description coverage is 100%, so the baseline is 3, and the description adds real meaning on top: only fields to change need to be supplied, sibling_card_ids is required specifically for shared sources and must be copied exactly from list_cards, and field semantics follow create_cards. It stops short of enumerating individual field formats, which the schema already covers.

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

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

States a specific verb and resource ('Update 1-500 card sources atomically') and names the exact scope and batch limit. It also distinguishes itself from delete_cards and points to create_cards for field conventions, so an agent can tell it apart from siblings 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?

Gives explicit prerequisites ('Read list_cards first'), a conditional workflow for shared sources ('copy sibling_card_ids, and include only one edit per source'), and a named alternative with its own condition ('edits that remove cards are rejected: use delete_cards for confirmed removal'). Nothing about when to choose this tool 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.