NextLang

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

The description adds behavioral context beyond the annotations: it discloses deduplication ('Words the user already has are skipped, not duplicated') which aligns with the idempotentHint, and states the return summary ('Returns how many were added, already saved, or invalid'). This complements the 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 tight, front-loaded paragraph: intent first, then usage context, field guidance, dedup behavior, and return value. Every sentence adds value 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 save operation with 3 top-level and 4 nested fields, the description covers the key semantics (language pair, field meanings, dedup, return counts) so an agent can construct a correct call. Minor omissions like character limits are already in the schema, and the output is adequately described for a tool without an output schema.

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

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

With schema coverage at 67%, the description compensates for the missing 'words' schema description by explaining meaning of 'term', 'translation', and 'example'. It also reinforces the roles of learningLanguage and translationLanguage ('the language being learned' and 'its meaning'), adding clarity beyond the schema's short descriptions.

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

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

The description states a specific verb ('saves') and resource ('new words to the user's NextLang vocabulary for one language pair'), explicitly linking to the spaced-repetition schedule. This clearly distinguishes it from siblings such as search_vocabulary or list_due_words, leaving no ambiguity about its function.

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

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

It provides an explicit trigger condition ('Use when the user asks to save or add words, for example from a text you discussed') and gives field-level guidance ('Put each word in 'term'...'). While it doesn't name alternative tools for when this shouldn't be used, the context is clear enough for an agent to select it appropriately.

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 are four uninformative false hints (readOnly=false, openWorld=false, idempotent=false, destructive=false), so the description carries the full behavioral burden. It reveals the 1-credit cost, the confirmation requirement before charging, the dedup behavior across calls, and the exact return payload (cards added, new total, remaining credits). This is rich behavioral context well beyond the annotations, with no contradiction.

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

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

Three sentences, each earning its place: core purpose + dedup, cost + confirmation gate + parameter sourcing, then return values. The most decision-relevant information (what it does, what it costs) is front-loaded, and there is zero filler.

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

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

With no output schema, the description correctly discloses return values. All three required parameters are addressable via schema plus the list_decks sourcing hint, and the absence of meaningful annotations is compensated by the cost/confirm/dedup details. The only gaps are unexplored failure modes (insufficient credits, nonexistent deck) and an explicit 'vs add_vocabulary_items' exclusion.

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

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

Schema coverage is 67% — deckId has no schema description. The description compensates for that gap with an actionable instruction ('Get deckId and platform from list_decks') that constrains both parameters' provenance and ensures the agent fetches valid values. It adds genuine meaning beyond the schema, though it adds nothing about count beyond the schema's 1-30 range.

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 ('Adds new cards') on a specific resource ('one of the user's existing NextLang decks'), and adds scoping detail ('avoiding cards it already has' = dedup). This differentiates it from siblings like generate_deck (creates a deck) and add_vocabulary_items (adds vocab items), so an agent can select it 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 description gives clear contextual usage guidance: 'Costs 1 credit: confirm first unless the user explicitly asked' is a conditional go/no-go instruction, and 'Get deckId and platform from list_decks' names the prerequisite step. However, it never explicitly names sibling alternatives or states when not to use this tool, so it stops short of full 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 are all false and provide zero behavioral signal, so the description carries full burden — and it delivers. It discloses the 1-credit cost, that the deck is persisted to the user's account, a precise confirmation protocol for tentative requests, and the non-idempotent failure mode ('generating again spends another credit'). No contradiction with the annotations; idempotentHint: false aligns with the disclosed double-spend risk.

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 but every sentence earns its place: cost, confirmation rule, prompt semantics, card-type limitation, return value, platform import guidance, credit-check avoidance, and failure recovery are all distinct payloads. The most critical facts (what it does, cost, confirm-first) are front-loaded. It is dense rather than bloated, though it could be tightened by merging the two confirm-first sentences.

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

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

With no output schema and empty annotations, the description alone must cover behavior, cost, and return values — and it does, including 'Returns the cards, a link to the deck on NextLang... and the remaining credits.' The failure paths (low balance, timeout) are both handled with concrete recovery instructions. For a 6-parameter, side-effecting tool this is about as complete as a description gets.

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: it defines what 'prompt' can be ('a topic, a situation or a short text of up to 500 characters'), states that learningLanguage determines the card front, and constrains output to basic front/back cards — which shapes how prompt and language params behave. count and level are already richly documented in the schema, so the marginal addition here is meaningful but not exhaustive.

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 precise verb+resource: 'Generates a new flashcard deck with NextLang's own generator and saves it to the user's account.' The word 'new' explicitly differentiates it from expand_deck, and the generate/save semantics separate it from get_deck, save_deck, and add_vocabulary_items. The function is immediately distinguishable from all ten siblings.

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

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

Exceptional. It explicitly says when NOT to use alternatives: 'Do not call get_credits first' and 'If this call fails or times out, call list_decks before trying again.' It also states the confirmation condition ('unless the user explicitly asked for a new deck, confirm first'), what not to promise (cloze decks are made on the website), and how to route Quizlet/Brainscape imports. This is the gold standard for sibling 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?

The description adds substantial behavioral detail beyond the readOnlyHint annotation: it explains the null semantics of freeCreditsRenewAt, instructs the agent on what to do when the balance is too low, and explicitly says not to push a purchase. These are non-obvious behaviors that an agent needs to know.

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 every sentence adds value: the first defines the return values, the second explains the low-balance handling policy, and the third provides relevant cost context. It front-loads the most important information and avoids fluff.

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

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

For a no-parameter, read-only tool with no output schema, the description is sufficiently complete. It explains the response semantics, the null case, the follow-up behavior with plansUrl, and the one-credit cost context, giving the agent everything needed to invoke and react to the tool correctly.

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

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

The tool has zero parameters and the schema is empty with 100% coverage, so there are no parameter details to document. This matches the rubric baseline of 4 for zero-parameter tools; no additional parameter compensation is needed.

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

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

The description clearly states a specific verb and resource: it returns the user's credit balance, premium status, and freeCreditsRenewAt. It is unambiguous and naturally distinguishes itself from sibling deck- and review-related tools, since no other sibling focuses on credit balances.

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

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

There is no explicit statement of when to use this tool versus alternatives, nor any named sibling comparison. The last sentence, 'Each deck generation or expansion costs 1 credit,' implies this tool should be used in the context of checking affordability before generating or expanding decks, but the guidance remains implicit.

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

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

Annotations already cover readOnlyHint=true and destructiveHint=false, so the description need not restate safety. It adds useful context: the deck is user-scoped ('one of the user's decks') and the return includes both cards and a NextLang link. It stops short of describing errors or pagination, but that is minor for this 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?

Two front-loaded sentences with zero redundancy: first states the primary action and output, second gives parameter sourcing. Nothing could be trimmed without losing value.

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

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

For a simple two-parameter, read-only getter, the description fully supports selection and invocation: it states what is returned and where to get valid parameter values. No output schema exists, but the description gives the high-level return shape (cards and link), which suffices.

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% (deckId lacks a description), so the description compensates by defining deckId as identifying one of the user's decks and by giving provenance for both parameters via 'Get deckId and platform from list_decks'. This adds real meaning beyond the schema.

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

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

The description uses a specific verb ('Returns') and a specific resource ('cards of one of the user's decks and its link on NextLang'), clearly distinguishing it from sibling tools like list_decks (which lists) and get_deck_file (which returns a file). The scope is precise: one user-owned 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 gives a clear prerequisite: 'Get deckId and platform from list_decks', which tells the agent exactly how to obtain valid parameters. It does not explicitly state when-not-to-use or name alternatives, but the 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is already known. The description adds valuable behavioral context beyond annotations: the one-hour link expiry, the instruction to show the link exactly as returned, the need to call again for a fresh link, and the Premium gating behavior with a clear error message. It doesn't mention rate limits or what happens if audio can't be generated, but the key behavioral traits are disclosed.

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 well-organized. It front-loads the core function, then covers the Premium requirement, link expiry, and alternatives. Every sentence adds useful information. It's slightly long, but for a tool with this many behavioral nuances (Premium, expiry, sibling routing), the length is justified. The structure flows logically from what the tool does to how to handle the result.

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

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

Given the tool's complexity (Premium gating, time-limited links, multiple output formats, sibling routing), the description covers the essential operational details. There's no output schema, so the description's mention of the download link and its one-hour validity is important. It could mention what the error response looks like for non-premium users, but it does say 'a non-premium account gets a clear message with a link explaining Premium,' which is sufficient for an agent to handle the failure case.

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

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

Schema description coverage is 50%: the platform parameter is described in the schema ('anki gives an .apkg file, mochi gives a .mochi file'), but deckId has no schema description. The tool description compensates by explaining the file formats and the context of deck import, and it clarifies that the platform enum maps to specific file types. It doesn't add detail about deckId format, but the schema already constrains it (string, 1-64 chars). The description adds meaningful context about what the parameters produce.

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: 'Returns a download link for one of the user's decks as a file to import.' It specifies the resource (user's decks), the action (returns a download link), and the file formats (.apkg for Anki, .mochi for Mochi). It also distinguishes itself from siblings like get_deck and list_decks by noting that those are for text-import platforms like Quizlet and Brainscape.

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

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

The description provides explicit when-to-use guidance: 'Premium only; call it directly, without checking get_credits first.' It also gives clear alternatives: 'for them give the deck link from list_decks or get_deck' and 'Show the cards as text only as a fallback.' This is excellent routing information that tells the agent exactly when to use this tool versus siblings.

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

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

Annotations already declare this as read-only and non-destructive, so the description adds value by disclosing behavior not in the annotations: newest-first ordering, inclusion of language pair and link, and the total count beyond listed results. This gives useful context about what the tool actually 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?

The description is front-loaded with the core listing behavior and then adds only high-value use-case guidance. Every sentence earns its place; no filler or repetition of schema details.

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

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

With no output schema, the description explains the main return aspects (deck, language pair, link, total) and gives real usage contexts. It lacks an exact response shape or explicit platform-filter guidance, but the provided details are sufficient for safe and correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining how filters relate to counting questions and by clarifying that query is the only way to reach older decks. This enriches the parameter usage guidance.

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

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

States a specific action ('Lists the user's most recent NextLang decks, newest first') with a clear resource and key scoping details. The description also differentiates when to use it for counting, searching, showing, and post-generate verification, which separates it from siblings like get_deck and generate_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?

Provides explicit when-to-use guidance: answer 'how many decks' questions, filter rather than opening decks one by one, use query to find older decks, and check after a failed generate_deck call. This is actionable direction with implied alternatives and exclusions.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds substantial behavior beyond that: it lists dictionaries with word counts when called without a pair, clarifies that a dictionary is identified by pair not direction, exposes dueTotal and nextDueAt semantics, and describes the interactive expectation of not revealing answers. This is valuable context the structured fields 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 long but every sentence earns its place: usage guidance, scoping rules, interactive behavior, and follow-up action are all covered without repetition. It is front-loaded with the primary use case and then expands into needed details, making it easy for an agent 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?

With no output schema, the description carries the burden of explaining return-like concepts, and it does: dueTotal, nextDueAt, dictionary word counts, and language-pair identification. It also covers the no-pair call flow, the all-mode fallback, and the required follow-up with record_review. An agent has enough information to invoke this tool correctly in the intended scenarios.

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 75%; mode and the language parameters are already described. The description adds meaning by explaining that the same dictionary can be quizzed in either direction, that a dictionary is identified by its pair, and that mode 'all' should be used when dueTotal is zero. Limit is the one parameter not addressed, but it is self-explanatory and constrained by 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 opens with a specific use case: 'review, practise or be quizzed on their NextLang vocabulary.' It clearly identifies the tool's resource (NextLang vocabulary) and differentiates it from sibling tools by stating when to call without a language pair versus with one, and by naming record_review as the follow-up. The distinction between dictionary identity and quiz direction further removes ambiguity.

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

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

The description gives explicit when-to-use instructions: call without a pair first, then call with the pair. It even provides a conditional: if dueTotal is 0 and the user wants to practise, call again with mode 'all' instead of switching to another dictionary. It also tells the agent not to reveal answers and to save results with record_review, covering next steps.

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

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

Annotations are all false, so the description carries the burden. It discloses the write nature ('Saves'), the effect of each rating ('unknown' sends word back to start), and the return value (new box 0-4 and next due date). It does not explicitly mention idempotency or error scenarios, but the directive to call once implies non-idempotency. This is solid transparency beyond the annotations.

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

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

The description is longer than ideal but every sentence carries purpose: main action, timing, special case (practice), rating definitions, and return info. It is front-loaded with the core purpose and well-organized, avoiding 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?

Given the tool's write nature and single parameter, the description covers when to call, what to pass, how to rate, and what to expect in return. It lacks explicit mention of error handling, rate limits, or prerequisites (e.g., word must exist), but these are not critical for correct invocation. The output is described sufficiently despite no output schema.

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

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

The schema defines the 'reviews' array but gives no semantics for the rating values. The description adds critical meaning: 'known' requires recall without a hint, 'unknown' sends the word back to the start. It also implies the 'id' is the word identifier via 'every word asked.' This compensates for the 0% schema coverage on semantic meaning.

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: 'Saves a quiz round to the user's spaced-repetition schedule.' It specifies the resource (quiz round) and the destination (schedule), and it establishes the tool's role as the only one that records review results, distinguishing it from siblings like save_deck or list_due_words.

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

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

Provides explicit timing instructions: 'Call once at the end of every round with every word asked, not after each word.' It also clarifies that practice rounds (mode 'all') must be recorded, and the instruction 'never offer a round that is not recorded' reinforces when the tool is required. Rating semantics are explained with concrete criteria for 'known' vs 'unknown'.

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 all false (not read-only, not destructive), so the description carries the disclosure burden and adds real value beyond them: the cost behavior ('for free (no credits)'), deduplication behavior ('Repeated fronts are dropped and reported as skipped'), and the card-orientation/swapping rule when the learning language is ambiguous. It does not fully cover side effects such as whether an existing deck with the same name is overwritten, which keeps it from 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?

The purpose and cost are front-loaded in the first sentence, and every subsequent sentence contributes distinct information: usage context, card orientation, dedup behavior, and sibling routing. It is slightly long at six sentences, with minor redundancy between 'user provided or that you wrote together' and the word-list/table examples, but no wasted sentences.

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 6-parameter mutation tool with no output schema, the description covers the essentials: purpose, cost, input formats, card directionality, dedup behavior, and alternative tools. The main gap is that it doesn't describe the response format beyond 'reported as skipped' — with no output schema, some return-value guidance would fully close the loop.

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 83% (above the 80% baseline of 3), and the parameter descriptions already document that front is in learningLanguage and back is the translation. The description adds meaning beyond the schema by explaining how to resolve ambiguity ('ask when that is unclear, and swap each pair so the front is in learningLanguage'), which clarifies the relationship between the language parameters and the cards array.

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 first sentence states a specific verb and resource ('Saves flashcards ... as a deck in the user's NextLang account') and adds the cost qualifier 'for free (no credits)'. It also differentiates from siblings by explicitly naming generate_deck and get_deck_file as the alternatives for other situations.

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 explicit when-to-use guidance: 'Use it to turn a word list, a table or an export the user pasted into a deck.' It also states exclusions and routing: 'For an .apkg (Anki) or .mochi (Mochi) file, call get_deck_file next; for Quizlet and Brainscape, give the deck link' and 'use generate_deck instead' for topic-written cards. 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 readOnlyHint and non-destructive behavior. The description adds useful behavioral context beyond that, including fragment matching and normalization ('ignores case and diacritics'). It does not contradict the read-only annotation and meaningfully complements it.

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

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

Three short sentences deliver purpose, matching behavior, and a usage directive, with no filler or repetition. The most important information is front-loaded, and every sentence earns its place.

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

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

For a read-only search tool with annotations covering safety, the description is nearly complete. It lacks an explicit description of the result shape, which would be useful since there is no output schema, but the usage guidance and search semantics give an agent enough 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 documents language parameters but leaves query and limit without descriptions. The description clarifies that query is a fragment of either term or translation, which is helpful, but it doesn't explain the limit parameter's semantics or how language filtering interacts with the search. With 50% schema coverage, the description only partially compensates.

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 ('Finds'), resource ('words in the user's NextLang dictionaries'), and search criteria ('fragment of the term or its translation'). It is clearly distinct from sibling tools like list_decks or list_due_words, and the search scope is unambiguous.

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

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

The instruction 'Call this before telling the user a word is not in their vocabulary' provides a clear, actionable trigger for use. It doesn't discuss when-not usage or alternatives, but as the only search tool among siblings, this is acceptable.

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