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?

Annotations (`readOnlyHint: true`) already cover read-only safety. The description goes beyond this by explaining the grouped output lists (`not_in_deck`, `known`, `struggling`), the `skipped` array behavior with the `answered_as` field, and the defaulting behavior of `lang`. The only minor gap is not detailing pagination or rate limits, but the provided context is substantial.

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 packed with valuable information, front-loading the main purpose. It covers usage, return structure, edge cases (`skipped`), and defaults. The only slight miss is being somewhat lengthy, but every sentence earns its place, making the informational density high.

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 batch lookup tool with 2 params and no output schema, the description thoroughly explains the return values (mastery levels, `skipped` handling, `lang_defaulted`). It covers the main use case (pre-glossing check) and edge cases (duplicates, unknown languages), making it highly 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?

The input schema already has 100% coverage with useful descriptions for both `words` and `lang`. The description adds crucial information about the return structure, which the schema lacks. However, the schema already explains the parameters well, so while the description enhances understanding of behavior, it doesn't add significant semantic detail about the parameters themselves beyond what's already 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 opens with a specific verb and resource: 'Batch lookup: for a list of target-language words, tell me which ones are already in the user's Minddory deck and how well they know each.' It clearly explains the batch nature and differentiates itself from siblings like get_card by stating 'Prefer this over calling get_card once per word.'

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 instructions on when to use it ('Use this BEFORE glossing or capturing vocabulary from a message'), what it answers ('which of these are actually new to this user'), and explicitly names the alternative ('Prefer this over calling get_card once per word'). This meets the criteria for explicit exclusions and 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?

ReadOnlyHint annotation already signals a non-mutating operation, and the description adds meaningful behavioral context by stating that results are derived from capture_word and log_interaction events and are frequency-ranked. It doesn't describe output shape or empty-result behavior, but this is minor given the read-only, aggregated nature of the 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 sentences, front-loaded with the core definition and followed by an actionable use-case statement. Every clause earns its place and no redundant material is present.

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

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

The tool is simple (no required params, no nested objects, no output schema), and the description covers the source data, computation window, ranking, and intended use. The schema handles parameter details, so the description is complete for agent selection and 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%: lang, limit, and lookback_days all have descriptive text including defaults and matching behavior. The description adds no parameter-specific information, so baseline 3 is appropriate.

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

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

Description opens with the specific action 'Get' and clearly defines the resource: 'the user's most actively encountered target-language words... ranked by frequency over a lookback window.' It distinguishes itself from sibling tools by explicitly sourcing from 'past capture_word + log_interaction events' and highlighting the frequency-rank aggregation.

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 guidance with 'Use to surface frontier words... when they ask what should I learn next or when you want context-aware suggestions.' This is clear when-to-use context, though it does not name alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral details beyond that: lookups are case-insensitive and the result includes translation, mastery, and the last 10 events. Since there is no output schema, these return details meaningfully set expectations. It does not cover not-found behavior, but enough is 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?

Two short sentences deliver the purpose, lookup behavior, and expected return fields with no filler or redundancy. Every phrase in the description adds useful information.

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

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

For a simple read-only single-card lookup with two parameters and no output schema, this description is mostly complete: it identifies the key parameter, mentions case-insensitivity, and enumerates return contents. It could add a short note on not-found behavior or a clearer 'use this when' hint, but the current level is solid for this low-complexity 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 coverage is 50%; the schema documents 'lang' thoroughly, while 'word' only has length constraints. The description clarifies that 'word' is the lookup key and case-insensitive, adding some meaning beyond the schema. However, it does not fully compensate for all param semantics and does not mention lang behavior beyond what the schema already says.

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 identifies the operation as 'Get single card detail by word', with a specific resource (card), a specific lookup key (word), and explicit scope (a single card). This distinguishes it from sibling list-oriented tools like get_known_words and get_active_vocab.

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 usage context is implied: use this tool when you need the detail of one card by its word. However, it does not explicitly say when not to use it, mention prerequisites, or contrast with sibling tools such as check_words or get_known_words. Given the context is clear but exclusions are absent, an implied-usage score is 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?

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds the pagination method (keyset on flashcards.id) which is useful behavioral context, but doesn't disclose details like whether results are sorted, or if the cursor is opaque. No contradiction with annotations.

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

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

Two sentences, zero waste. The first sentence states the purpose, the second provides the pagination detail. Front-loaded and efficient.

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 is simple (3 optional params, no output schema) and the description covers the core purpose and pagination. However, it doesn't mention what the response contains (e.g., word objects, metadata) or any ordering guarantees, which could be important for an agent. Given the simplicity, it's adequate but not 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 only 33% (only 'lang' has a description). The description adds context for 'lang' (user's primary learning language default) but doesn't explain 'limit' or 'cursor' beyond schema constraints. Since coverage is low, the description should compensate more, but it does add some value for the lang parameter.

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

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

The description clearly states the tool returns words the user has verified as known via flashcard practice, with a specific pagination method (keyset on flashcards.id). It distinguishes from siblings like get_active_vocab and get_queue by focusing on known words, though it doesn't explicitly name alternatives.

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 usage for retrieving known words but doesn't explicitly state when to use this vs. alternatives like get_active_vocab or check_words. The pagination hint is useful but no exclusions or alternative tool names are provided.

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 covers the safety profile, and the description adds a useful temporal behavior detail. However, it does not disclose ordering, pagination, how overdue cards are treated, or what the returned objects contain.

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 filler. Every word contributes to the core meaning, making it highly scannable.

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 queue lookup, the description captures the essential return criterion and pairs well with the readOnlyHint annotation. However, the absence of an output schema and the unstated meaning of 'max' leave some details to be inferred.

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 description provides no information about either parameter. The schema describes 'lang' well but leaves 'max' with only min/max bounds, so the agent must infer that 'max' caps the returned queue size; with 50% schema coverage, the description should have compensated but does not.

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 defines the tool's purpose: it returns cards that are due now or within the next 24 hours. This specific time-based scope distinguishes it from siblings like get_known_words or get_active_vocab.

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 selection criterion is explicit ('due now' and 'due within the next 24 hours'), giving clear context for when an agent should request this queue. It does not explicitly name alternatives or exclusions, but the intended usage 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?

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 indicate a non-read-only, non-destructive operation (readOnlyHint=false, destructiveHint=false). The description adds that it 'appends' a 'generic interaction event', which implies non-destructive append semantics. However, it does not disclose any further behavioral traits like side effects, permission requirements, or log size constraints. With annotations covering the safety profile, this is sufficient but not rich.

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, well-structured sentence that front-loads the core action and then lists concrete use cases. No wasted words; every part contributes to understanding.

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 is simple (4 params, no output schema), and the description covers purpose and usage adequately. However, since parameter semantics are only partially covered and there is no output description, the description is incomplete for fully understanding behavior. It is minimally viable but could benefit from parameter examples or a note about what the log entry contains.

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 25% (only 'lang' has a description). The description does not explain the 'type', 'word', or 'metadata' parameters, and the enum values for 'type' are not elaborated. Since the schema only clarifies 'lang', the description should compensate for the other parameters but fails to do so, leaving semantic gaps.

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?

Clearly states the verb 'Append' and the resource 'answers log', and specifies the three interaction domains (lookups, AI discussions, reading-in-context). This distinguishes it from sibling tools like capture_word or mark_demonstrated, which are about capturing or marking specific states.

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 use it ('for lookups, AI discussions, and reading-in-context signals'), giving clear contexts. It does not enumerate when-not-to-use or alternatives, but the listed use cases are enough to guide selection relative to 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 declare non-read-only (readOnlyHint=false) and non-destructive (destructiveHint=false), which is appropriate for a write operation that modifies the schedule. The description adds that it 'logs an answer row' and affects the review schedule, but does not disclose side effects like overwriting or requiring authentication. It 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 two sentences, front-loaded with the core purpose and effect, and adds the critical edge case about missing flashcards. No wasted words.

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

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

For a 5-parameter tool with no output schema, the description is reasonably complete: it explains the purpose, the effect on the schedule, and the edge case behavior. However, it lacks explicit guidance on parameter interactions (e.g., how 'source' and 'context' are used) and does not describe the return value or success criteria, but it is adequate for most use 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 only 20%, but the description clarifies the 'confidence' parameter: it determines the boost weight, and mentions the 'lang' parameter's behavior (scoped on base). However, it does not add semantic detail for 'word', 'source', or 'context'. The description adds some value beyond the schema but not enough to fully compensate for the low 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 clearly states the tool's purpose with a specific verb ('mark') and resource ('word demonstrated'), and specifies the effect ('Confidence-weighted spaced-repetition boost...'). It distinguishes from the sibling tool 'mark_struggled' by indicating it is for correct usage.

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: when the user has used a word correctly InternetHigh, and implies the opposite for 'mark_struggled'. Also notes that it logs an answer row even if no flashcard exists, which is a key contextual detail.

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 transparently discloses the effects of the operation: card comes back sooner, ease factor drops, interval resets, repetitions reset. This goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by explaining exactly what changes occur, which is valuable for the agent to understand side effects.

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

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

The description is concise and to the point, using two sentences to convey the action and its results. There is no unnecessary verbosity or repetition, making it easy for an agent to parse quickly.

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

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

The description explains the purpose and behavioral effects clearly, but it lacks context about what parameters are required (e.g., what 'source' and 'context' are for) and does not mention any return value or success criteria. While there is no output schema, the parameter ambiguity and lack of directions on when to use versus not use the tool make it only moderately 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?

The input schema has four parameters (lang, word, source, context), but only 'lang' has a description, giving 25% coverage. The tool description does not compensate by explaining the meaning or usage of 'source' and 'context', leaving ambiguity. Since coverage is low, the description should have added parameter context, but it does not.

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

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

The description clearly states the tool's purpose: to degrade spaced repetition for a word the user got wrong, with explicit effects (card comes back sooner, ease factor drops, etc.). It distinguishes from siblings like 'mark_demonstrated' by focusing on the 'struggled' state.

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 when to use it (when the user got a word wrong) and explains the consequential behavior. However, it does not explicitly contrast with alternatives like 'mark_demonstrated' or provide explicit direction on when not to use it, though the context strongly suggests the intended scenario.

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