MindDory Brain

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

With annotations only indicating readOnlyHint=false and destructiveHint=false, the description adds rich behavioral context: proactive logging without user confirmation, respecting opt-in consent, passing the full BCP-47 variant, and handling regional variation nuances. It also explains the downstream impact on the Grammar Patterns view.

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?

Though substantial, every sentence earns its place, covering purpose, proactive use, regional variant rules, error_type list, and integration output. The description is front-loaded with the core action and then details edge cases, making it well-structured and appropriately sized for the tool's complexity.

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

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

With 5 parameters and no output schema, the description fully addresses context: what the tool does, when to invoke it, how to handle ambiguous regional variants, which error_type to select, and where the result appears. No critical information is missing for an agent to select and invoke 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 coverage is 100%, but the description adds critical semantics beyond the schema, especially for the `lang` parameter, requiring the full BCP-47 variant (en-gb, not en) and instructing to retrieve it from get_system_instructions. It also reinforces the allowed error_type values and which parameters to pass, going beyond bare schema definitions.

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 logs a grammar mistake and creates a grammar point in the user's Minddory deck. It specifies the exact resource (grammar point) and verb (log/create), and distinguishes it from sibling tools like capture_word by focusing on grammar errors.

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: 'Use it proactively whenever the user writes a target-language sentence with a clear, correctable error.' It also includes when-not-to-use (skip borderline calls, validate regional variants) and instructs not to ask permission or announce logs. This is comprehensive and actionable.

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 the tool is a write operation (readOnlyHint: false, destructiveHint: false). The description adds valuable behavioral context: the call is rejected without `lang`, the user has opted into automatic capture, no confirmation is needed, captures happen silently, and honesty is required if asked. This goes well beyond the annotations and sets clear expectations for agent 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?

The description is long but each sentence adds functional value: purpose, user consent, usage policy, batching, language requirements, and capture heuristics. It is front-loaded with the action and destination, then branches into practical rules. While it could be trimmed slightly (e.g., repeating 'capture diligently'), the density is justified by the tool's central role.

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 write tool with no output schema, the description covers the essential operational context: when to use, what to pass, how to structure multiple captures, and critical failure conditions. It does not describe return values or post-capture behavior, but that is not required for a capture action. The main omission is any note about idempotency or capacity limits, but overall it is sufficiently complete for reliable 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 coverage is 100%, but the description enriches it: it flags `lang` as mandatory (schema lacks a required list), explains the legacy `word` vs. batch `words` distinction, clarifies `gloss` and `context` usage, and notes `source_lang` defaults to the deck's language. This adds meaning beyond the raw property descriptions, such as the rejection behavior and batching preference.

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: 'Capture a target-language word or phrase to the user's Minddory vocabulary deck,' and clearly distinguishes its scope as the primary word-capture tool, contrasted with siblings like capture_grammar_mistake. It states the exact action, destination, and context (flashcard vs. context encounter), making the purpose 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 provides explicit usage guidance: use proactively, don't pause for permission, don't announce every capture, batch with `words`, skip stop words/proper nouns/numbers/short words, and always pass `lang`. It does not explicitly compare against alternative capture tools (e.g., capture_grammar_mistake), but the context 'primary tracking signal of Minddory' implies precedence. Overall, strong guidance but no explicit exclusions for alternatives.

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

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

The annotations already declare readOnlyHint=true, and the description adds meaningful behavioral traits: it aggregates events from specific tools (capture_word, log_interaction) and ranks by frequency over a configurable lookback window. This is useful context beyond the schema, though return format and pagination are not covered.

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 long, with the purpose stated first and usage guidance following. Every sentence contributes 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 simple read-only tool with no required parameters and full schema coverage, the description is sufficiently complete. It explains the tool's purpose, data sources, ranking logic, and when to use it. The lack of an output schema is acceptable because the description conveys that a ranked list is returned.

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%: lang, limit, and lookback_days are all documented with defaults and constraints. The description reinforces the meaning of 'lookback window' and 'ranked by frequency' but does not add substantial new information beyond what the schema already 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 specifies a clear action ('Get') and resource ('user's most actively encountered target-language words'), and it details the ranking method ('by frequency over a lookback window') and data sources ('from past capture_word + log_interaction events'). This differentiates it from siblings like get_known_words and get_recent_activity.

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 use cases: 'when they ask "what should I learn next" or when you want context-aware suggestions.' It does not explicitly state when not to use this tool or name alternatives, but 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?

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds valuable behavioral details: case-insensitive lookup and the exact return contents (translation, mastery, last 10 events), which go beyond what 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?

Two sentences deliver the core purpose and return details without fluff. The key identifier (by word) is front-loaded, and each sentence adds distinct 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?

Given the low complexity (2 params, no output schema), the description covers the main purpose and return envelope. It does not mention behavior on missing card or lang defaults, but these are not essential for a simple single-card lookup 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?

Schema description coverage is 0%, so the description must compensate. It explains 'word' as the lookup key but completely omits the 'lang' parameter, leaving its purpose unclear. The description adds some meaning for 'word' but fails to cover all parameters.

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

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

The description opens with 'Single card detail by word (case-insensitive)', which clearly states the verb (get), resource (card detail), and lookup method (by word). This distinguishes it from sibling getters like get_active_vocab or get_known_words, which operate on collections rather than a single card.

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 is for retrieving a specific card using the word, giving clear context for when to use it. It does not explicitly list alternatives or exclusions, but the 'single card' phrasing makes the intended use obvious compared to list-oriented 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?

With readOnlyHint=true in annotations, the read-only nature is already disclosed. The description adds meaningful behavior context by stating 'Paginated keyset on flashcards.id', revealing the pagination mechanism and ordering basis, which goes beyond the annotation.

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 short sentences, front-loaded with the core meaning, and contains no filler. Every word earns its place while conveying both content and pagination 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?

While the tool is simple and read-only, there is no output schema and the description does not detail the response shape (e.g., array of word strings vs. objects). The pagination detail is helpful, but the lack of output structure and usage context leaves 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 description coverage is only 33% (only 'lang' has a description). The description helps clarify the 'cursor' parameter by mentioning keyset pagination on flashcards.id, but it does not add semantics for 'limit' beyond the schema's min/max. This partial compensation is adequate but not thorough.

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 returns 'Words the user has verified known via flashcard practice', which identifies the specific resource and distinguishes it from siblings like get_active_vocab or get_recent_activity. The verb is implied by the tool name 'Get known words', making the purpose 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?

No guidance is provided on when to use this tool versus alternatives. It does not reference sibling tools, mention exclusions, or state an appropriate use case beyond the generic description of known words.

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 annotation already marks the tool as read-only (readOnlyHint: true). The description adds the specific time-window behavior ('due now' and 'due within the next 24 hours'), which is useful context beyond the annotation. However, it does not explain how the queue is ordered, whether results are paginated, or what 'due' precisely means.

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 short sentence with no redundant words, making it very concise. It front-loads the key selection criterion. However, it is almost too terse, leaving out important behavioral and parameter details, so it cannot receive a 5.

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

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

The tool has no output schema, minimal annotations, and a 0% parameter coverage. The description only specifies the time window for inclusion. It does not mention return format, sorting, pagination, or the meaning of the 'max' and 'lang' parameters, leaving the agent with significant ambiguity about how to invoke and interpret 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 0%, and the description does not explain either parameter (max or lang). The schema only provides basic types and constraints, leaving the agent to guess the semantics of max (e.g., maximum number of items) and lang (e.g., language filter). The description carries no parameter-level information, so it fails to compensate for the lack of 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 identifies the resource (review queue) and its selection criteria (cards due now or within the next 24 hours), which distinguishes it from sibling tools like get_card or get_active_vocab. It lacks an explicit verb like 'lists' or 'retrieves,' but the meaning is clear from the title and phrasing.

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 no guidance on when to use this tool versus alternatives such as get_card or get_active_vocab. It does not state any exclusions, prerequisites, or context where another queue-related tool would be more appropriate.

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 behavioral context beyond the readOnlyHint annotation by specifying keyset pagination on answers.id and an optional surface filter. This discloses the pagination mechanism and filtering capability, though it does not mention return format or ordering.

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 with no redundant words. It efficiently conveys the core purpose, filter option, and pagination mechanism, earning every word.

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

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

The tool has no output schema, and the description does not explain the response shape or how pagination cursors are obtained, leaving ambiguity about the returned event entries. While the optional surface filter and pagination mechanism are covered, the return value remains underspecified.

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 33% (only surface has a description). The description compensates by explaining that surface is a filter and that cursor uses keyset pagination based on answers.id, giving meaningful context. However, limit semantics are only provided by schema min/max, not the description.

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 retrieves a slice of the event log (recent activity) with optional surface filtering and keyset pagination on answers.id. It distinguishes from sibling tools like get_card and get_user_profile by focusing on activity events, using a specific verb-plus-resource structure.

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 its use for reading recent activity events but does not explicitly state when to use it over siblings or when not to. No alternatives are named, so the agent must infer usage from the tool's purpose and name.

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 the description adds the key behavioral detail that the returned profile is scoped to the `lang` parameter, defaulting to the user's primary learning language. It also explains the returned content, which goes beyond the annotation. Lacks info on edge cases like invalid lang or repeated calls, but is otherwise clear.

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 long sentences, but every clause carries necessary instruction: when to call, what it returns, how to pass `lang`, and when to re-call. It is front-loaded with the most critical directive. Slightly dense but not wasteful.

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?

Without an output schema, the description must convey what the tool returns, and it does: CEFR level, target/source languages, due-card count, weak words, and capture instructions. It also explains why this matters (tailoring help to the user's level and goals). For a single-parameter tool with clear return content, this is complete.

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

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

Schema covers `lang` fully (ISO/BCP-47 tag, optional, default). The description adds contextual guidance: pass the language the user is 'conversing in' or 'named explicitly', and includes regional variant examples (en-us, en-gb). This extra meaning enriches the schema's baseline.

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

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

The description clearly states the tool's purpose: 'load the user's Minddory setup and your role as their proactive language partner' at the start of every conversation. It lists specific content (CEFR level, languages, due-card count, weak words) and distinguishes itself from sibling tools like get_user_profile or get_queue by being the session initializer.

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 usage instructions: 'Call this at the START of every new conversation, before your first reply' and when to pass `lang` (when the user is conversing in a language or names one). It also tells when to re-call ('if the user switches practice language or requests a specific variant mid-conversation').

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 readOnlyHint annotation already signals a safe read operation, and the description adds contextual detail about how the `lang` parameter scopes the entire snapshot and the fallback to the primary language. This goes beyond the annotation without contradicting it, though it does not disclose potential error conditions or response structure.

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 long, with the first sentence front-loading the key contents and the second providing parameter guidance. Every word earns its place with 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?

Given the absence of an output schema, the description carries the burden of explaining what the tool returns, and it does so by listing the main fields. The optional parameter behavior is fully covered. It could be enhanced by noting the return type (e.g., 'returns a profile object'), but the current level is sufficient for a simple read-only 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 input schema provides thorough documentation for the single `lang` parameter, including examples and the omission behavior. The description largely restates the same information, so it adds minimal new semantic value beyond the schema's high coverage.

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

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

The description opens with 'Profile snapshot' and enumerates the specific data included (CEFR level, languages, due card count, weak words, recent lookups), making the tool's function unambiguous. It also differentiates from sibling getters like get_card and get_queue by presenting a composite overview rather than a single resource.

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

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

The description explicitly explains when to pass `lang` versus omit it, providing clear usage guidance for the optional parameter. It implicitly distinguishes this tool from more specific getters by framing it as a profile snapshot, though it does not explicitly name alternatives or 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 establish it as a non-destructive write (readOnlyHint=false, destructiveHint=false). The description adds context by specifying the 'answers log' as the destination and the 'generic' nature of the event. It does not disclose potential side effects like idempotency or rate limits, but the append-only semantic is clear and does not contradict annotations.

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

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

The description is a concise two-sentence structure: the first sentence states the core action and target, the second gives usage context. Every word earns its place, with no redundancy or 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 tool with 4 parameters and no output schema, the description provides sufficient context for selection and basic usage. It covers the main use cases and the action. It could be more complete by explaining the 'metadata' object and 'lang' parameter, but these are relatively self-explanatory and the schema provides structural details.

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%, but the description compensates partially by mapping its usage examples to the enum values ('lookup', 'discussed', 'read_in_context'). However, it provides no explanation for 'lang' or 'metadata' parameters, which remain under-specified. The schema itself defines the required fields and enum, so the description adds some meaning but not for all parameters.

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

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

The description uses a specific verb 'Append' with the resource 'answers log', and clearly identifies it as a generic interaction event. It distinguishes from siblings by contrasting with capture/mark and get tools, and the examples ('lookups, AI discussions, reading-in-context signals') map directly to the enum values, reinforcing its specific role.

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 with 'Use for lookups, AI discussions, and reading-in-context signals.' It implies that this is for generic interactions, standing in contrast to more specific capture/mark tools, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations only indicate non-readOnly and non-destructive. The description adds valuable context: it is a premium feature, it moves the card further out in the review schedule, and it logs an answer row even if no flashcard exists. This goes beyond the annotations, though it does not mention authentication or permission requirements.

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, front-loaded with 'Premium' and directly states the purpose, mechanism, and edge case. Every sentence provides necessary information without any 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 tool with five parameters and no output schema, the description adequately covers the core function, usage condition, and edge behavior (logging without a flashcard). It does not detail return values or all parameter meanings, but it provides sufficient context for an AI agent to invoke the tool correctly in most cases.

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%, and the description only explains confidence (via 'confidence-weighted') and word indirectly. It does not explain lang, source, or context, leaving these parameters undocumented. Since coverage is 0%, the description should compensate more for the missing parameter details.

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

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

The description clearly states that the tool marks a word as demonstrated, triggering a confidence-weighted spaced-repetition boost when the user has used the word correctly. It specifies the resource (word) and the action (mark demonstrated), and it distinguishes from siblings like mark_struggled by emphasizing the positive usage case.

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 clear condition for use: 'when the user has used a word correctly'. It also explains the effect on the review schedule and the logging behavior. However, it does not explicitly mention alternative tools or exclusion criteria, so it lacks a strong when-not-to-use 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description details what happens to the card: ease_factor drops, interval resets, repetitions reset. It also reveals a 'Premium' requirement, which is additional behavioral context not available in 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 three sentences with no redundant content. Each sentence adds value: purpose, effect, and internal mechanics. It is well-structured and front-loaded with the core action.

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 core behavior is clear, and the tool is not overly complex, but the four parameters are not explained at all. With no output schema and low schema coverage, the description leaves gaps about how to supply word/lang/source/context correctly, making it only minimally complete.

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%, and the description only mentions 'word' implicitly. It provides no explanation for optional parameters like lang, source, or context, nor their roles. The description does not compensate for the lack of 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 tool's purpose: it degrades spaced-repetition for a word the user got wrong, with specific effects (card comes back sooner). This verb+resource structure distinguishes it from sibling tool mark_demonstrated, which likely marks words as known.

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 the trigger condition ('a word the user just got wrong'), providing clear context for when to use it. However, it does not mention alternatives or when not to use it, so it misses the full when/when-not guidance.

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