NextLang

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

Annotations already signal idempotentHint and destructiveHint false, and the description reinforces this with dedupe behavior: 'Words the user already have are skipped, not duplicated.' It also discloses the side effect of entering the spaced-repetition schedule and summarizes what the return value contains, all beyond the structured 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 dense but every sentence earns its place: core action, when to use, parameter orientation, dedupe behavior, return summary, and sibling-tool routing. The most important information 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?

For a 3-parameter tool with no output schema, the description covers usage triggers, language-pair semantics, duplicate handling, return value contents, and the correct alternative tool. The enum values and constraints are already in the schema, so no critical guidance 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 67%, and the description compensates by giving field-level guidance: 'Put each word in term in the language being learned and its meaning in translation,' and it clarifies that example is optional and should be added 'when it helps.' This meaningfully exceeds what the schema alone provides.

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

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

The description opens with a specific verb and resource: 'Saves new words to the user's NextLang vocabulary for one language pair' and explains the consequence of joining the spaced-repetition schedule. It also distinguishes itself from sibling save_deck by explicitly stating this is not a flashcard deck, so an agent can tell the tools apart.

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 trigger: 'Use when the user asks to save or add words, for example from a text you discussed.' It also provides an explicit alternative and exclusion: when the user wants a deck for Anki, Quizlet, Mochi, or Brainscape, use save_deck instead.

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

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

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?

Beyond the readOnly/destructive annotations it discloses real behavior: due reviews are ordered before new words, new words are capped per dictionary per day by the New/day setting, nextDueAt indicates when scheduled review resumes, and the agent must not reveal the answer before the user replies. That is substantive operational context the annotations cannot carry.

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

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

Front-loaded with the use case, then sequencing, then behavioral constraints. It is on the long side and the sentence about answering which languages the user is learning partially restates the earlier no-pair behavior, but nearly every sentence carries actionable content.

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 4-parameter tool with no output schema, the description covers the call sequence, fallback mode, and references the key return fields (dueTotal, nextDueAt). It stops short of describing the word list shape itself, but an agent has enough to call and interpret the 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?

Schema coverage is 75%, and the description compensates for the unlabeled 'limit' by clarifying the pair semantics: 'term' is always learningLanguage and 'translation' is translationLanguage, and either quiz direction uses the same dictionary. The mode semantics are largely duplicated from the schema, but the pair-direction rule adds genuine meaning not present in the schema.

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

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

The description names a specific resource (due vocabulary words / dictionaries) and spells out both operating modes: called without a pair it enumerates dictionaries and word counts, called with a pair it returns the words due. It is clearly distinguishable from siblings like record_review and search_vocabulary.

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 explicit triggers ('when the user wants to review, practise or be quizzed'), a required call sequence (call without a pair first, then with the pair), a fallback path (use mode 'all' instead of switching dictionaries when dueTotal is 0), and a follow-up route to record_review. Nothing about when to pick 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.

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

Annotations cover the write/safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds real substance on top: the once-per-round call contract, the 'unknown' rating's next-day rescheduling effect, and the fact that results include next due dates and learned status. It stops short of covering failure behavior, permission requirements, or what happens on a duplicate call (relevant given idempotentHint=false).

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

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

Front-loaded with the core purpose, then usage rules, then rating semantics, then returns — a sensible order. Most sentences earn their place, though the 'never offer a round that is not recorded' clause drifts into product policy that is only loosely tied to invoking this tool.

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 usefully describes the return value (next due date and learned status at 21+ days). Combined with the call-frequency contract and rating semantics, an agent has enough to invoke correctly; only error handling and the id format are unaddressed.

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 0%, and the description compensates well by explaining the rating semantics ('known' only without a hint; 'unknown' brings the word back the next day) and that the array must carry every word asked. It does not explain the id field constraints (1-64 chars) or the 100-item cap, so a small gap 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 first sentence gives a concrete verb and resource: 'Saves a quiz round to the user's spaced-repetition schedule.' This is clearly distinguishable from siblings like add_vocabulary_items, save_deck, or list_due_words, which handle vocabulary/deck management rather than recording round results.

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

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

Explicitly states when to call ('once at the end of every round with every word asked, not after each word') and pre-empts a likely misuse case (practice rounds with mode 'all' still need recording). It even warns against offering an unrecorded round, which is a behavioral rule an agent could not infer elsewhere.

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 behaviors: saving is free and uses no credits, repeated fronts are dropped and reported as skipped, and language direction is normalized by swapping pairs so the front is in learningLanguage. It also explains how to disambiguate the learning language when the user did not specify 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?

The description is long but every sentence earns its place, covering purpose, language-direction rules, duplicate handling, and sibling-tool routing. It is front-loaded with the core purpose and then branches into usage distinctions, making it easy for an agent to extract the key facts.

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 tool with no output schema, the description covers all operational context an agent needs: what input formats are acceptable, how to handle ambiguous language direction, what happens to duplicates, and which follow-up tool or action applies per platform. No critical gap remains.

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 high (83%), so the baseline is already solid. The description adds real value by explaining that front must be in learningLanguage and back in translationLanguage, and by giving the rule to ask or swap when language direction is unclear. It does not add much for deckName or level, but the schema already documents those adequately.

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

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

The description states a specific verb and resource: it saves user-provided or co-written flashcards as a deck in the user's NextLang account. It also distinguishes itself from siblings by naming generate_deck, add_vocabulary_items, and get_deck_file as different operations, so an agent can immediately tell which tool is which.

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 explicit when-to-use guidance: turn a pasted word list, table, or export into a deck. It also provides exclusions and alternatives: use get_deck_file for .apkg/.mochi files, give a link for Quizlet/Brainscape, use generate_deck for topic-based card writing, and use add_vocabulary_items for the review schedule.

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.