Lingard Vocab

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety burden is off the description. The description adds only the word "live", hinting at fresh (non-cached) retrieval, and nothing about auth, rate limits, or failure modes. That is thin but not contradictory.

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?

A single front-loaded sentence with no wasted words. It is slightly incomplete for its length, since it omits the targetLang selector entirely, which is a content gap rather than verbosity.

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

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

An output schema exists, so return values need no explanation. However, with three alternative selectors and zero required parameters, the description should at least acknowledge the targetLang-only path that lets the tool be called with no id or uri. That omission leaves the calling options incompletely framed.

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

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

Schema description coverage is 100% and each parameter already documents precedence (id wins over uri, targetLang as fallback). The description only restates the id/uri selectors with the same examples, adding no new meaning. Baseline 3 applies.

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

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

States a specific verb and resource: fetches the full live Lingard JSON record for a given selector. It is clear what it does, but it does not differentiate itself from the closely related sibling lingard_get_learning_context, which the targetLang fallback overlaps with.

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 phrase "search-result id" implies this is called after search, but there is no explicit when-to-use or when-not-to-use guidance, and neither `search` nor `lingard_get_learning_context` is named as an alternative. Usage is only implied.

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 richly discloses write behavior, deduplication, writable-collection constraints, completeness requirements, and merge semantics. But its guarantee that it deduplicates by normalized title and never changes or clears already-filled values conflicts with the annotation idempotentHint=false, so this is an annotation contradiction.

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

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

Despite its length, the description is front-loaded with the core action and then adds necessary constraints in a dense, purposeful paragraph. The detail is justified by the complexity of the card model and merge 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?

The description is substantial for a complex write tool, and an output schema exists so return values need not be explained. The main remaining gaps are collection identification and explicit routing against sibling preview/fill/commit tools.

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 low at 29%, but the description compensates for many key parameters by explaining commit behavior, mergeMode defaults, allowIncompleteCards, writable collection constraints, noun articles, and {} example markers. It still leaves top-level collectionUuid, collectionTitle, and targetLang less explained than an agent might want.

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: adding vocabulary cards to an existing Lingard collection, with deduplication by normalized word title. It is clear about scope, but it does not explicitly distinguish itself from close siblings such as lingard_fill_missing_card_fields or the preview/commit workflow.

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 important preconditions: only writable="full" collections accept new cards, curated collections are read-only, and commit=true writes them. However, it does not explicitly say when to use this tool versus lingard_fill_missing_card_fields, lingard_preview_vocab_changes, or lingard_commit_vocab_changes.

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 destructive, non-idempotent, open-world; the description adds the substance behind that - existing card images are replaced, input formats are converted to WebP, and uploads land as private custom images. It stops short of covering permissions, size limits, or partial-failure behavior across a multi-entry batch.

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

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

Three sentences, no filler, with the core action first, the negative constraint second, and the format/write semantics last. Every sentence carries distinct 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 destructive batch mutation with an output schema present, the description covers intent, image sourcing, conversion, replacement, and the dry-run switch. The one missing piece is what targetLang and the top-level collection fields mean, which matters for 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 coverage is only 40%, and the description compensates for the image-source fields by explaining that each entry carries exactly one of imageBase64, dataUri, or imageUrl and that imageUrl is server-downloaded. However, top-level targetLang, collectionUuid, and collectionTitle get no explanation in either schema or description, leaving a real gap.

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 - 'Attaches supplied images to existing Lingard cards' - and immediately rules out the adjacent capability ('It does not generate images'). No sibling tool does image attachment, so a reader can place it unambiguously.

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 usage context: images must be supplied as base64/dataUri/url, and 'commit=true writes' implies the default is a dry run. It doesn't name a sibling alternative when a card is missing or when this should be preferred over other card-editing tools, but the when-to-use framing is solid.

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 flag destructiveHint=true, and the description earns credit for explaining why — overwrite_non_empty replaces already-filled values and clearFields wipes a stored grammatical form. It also discloses the validation gate (allowIncompleteCards) and required-field rules for new cards. It says nothing about idempotency or side effects on collections, so it is strong but not exhaustive.

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 action and the preview relationship; every sentence carries rules or constraints. The article example and {} marker sentences largely restate the nested schema descriptions, so a little redundancy is present, but nothing is padding.

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

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

For a destructive, deeply nested commit tool with an output schema, the description covers validation, merge semantics, and formatting conventions well. However, it never explains the required targetLang or how the target collection is identified (collectionUuid/collectionTitle/createIfMissing), leaving a required parameter and the destination 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?

Top-level schema coverage is effectively zero for targetLang/change, and the description compensates on the highest-risk semantics: form is not part of speech, the {} highlighting convention, and the article-on-noun-title rule. It also supplies meaning for mergeMode:"overwrite_non_empty" and clearFields:["form"], which the schema leaves bare. Untouched are targetLang, collectionUuid/collectionTitle, createIfMissing, and the cards-vs-words alias.

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

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

States a specific verb and resource ("Commits a ... Lingard vocabulary change") and names the upstream flow ("previously previewed or freshly supplied"), which hints at lingard_preview_vocab_changes without naming it. An agent can tell it is the write/apply step versus the preview step, but the sibling link is implied rather than explicit.

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?

"This is the tool that corrects existing cards" gives a clear use case and distinguishes it from the add/fill siblings, and the mergeMode/clearFields sentence explains the correction scenario concretely. It does not exclude cases (e.g. when to prefer lingard_fill_missing_card_fields or lingard_add_words_to_collection) or state whether preview is mandatory first.

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

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

Annotations already mark this as a non-read-only, non-destructive mutation. The description adds useful behavior beyond annotations: commit=true performs the write, allowIncompleteCards relaxes validation, and it specifies complete-card requirements plus article and {} formatting rules. It does not cover auth or failure behavior, but the key write semantics 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 front-loaded with the primary action and the important commit=true distinction, then moves into card validation and formatting rules. It is dense but appropriately sized for a complex creation tool, and every sentence adds relevant constraints, though the single-paragraph form could be more 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?

The tool has an output schema, so return values need not be described. However, with 9 parameters and very low schema description coverage, the description leaves several metadata parameters undocumented and does not fully clarify collection-level creation behavior. It covers the most important card and commit rules but is not complete for the tool's full surface.

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 very low at 11%, so the description must carry parameter meaning. It does explain the non-obvious semantics of commit, allowIncompleteCards, card fields, form, article handling, and {} highlighting, but several top-level parameters such as pic, icon, color, topic, targetLang, and collectionTitle are unexplained. It partially compensates, not fully.

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: "Creates a Lingard vocabulary collection", optionally with initial cards. It implies this is for new collections rather than adding to existing ones, but it does not explicitly name or differentiate from sibling tools such as lingard_add_words_to_collection. Still, the core purpose is clear.

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

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

The description explains that commit=true writes the collection and describes card completeness requirements, but it gives no explicit when-to-use guidance versus alternatives like preview, commit, or add-words tools. It also does not state when not to use this tool or what workflow it belongs to.

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 flag non-read-only, non-destructive, non-idempotent; the description adds real value on top by disclosing the additive-only semantics and the read-only status of curated collections. 'commit=true writes' implies commit=false is a dry run, though it is left implicit and error/permission behavior is unstated.

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 tight sentences, front-loaded with the core action and the non-overwrite guarantee; every sentence carries distinct information and none repeats annotations verbatim.

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 output schema removes the need to describe returns, and annotations cover safety, but for a 5-parameter mutation tool the description leaves card-matching, collection targeting (uuid vs title), and dry-run behavior undefined. Adequate minimum, with clear gaps an agent must guess at.

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?

Top-level schema description coverage is reported as 0%. The description explains only the commit flag; targetLang, collectionUuid, and collectionTitle are entirely undocumented, and nothing says how provided cards are matched to existing cards (title, alias, uuid).

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

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

States a specific verb and resource ('Fills empty fields on existing Lingard cards') and adds the defining constraint 'never overwrites or clears a field that already has a value', which cleanly separates it from sibling update tools such as lingard_update_example_translations.

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

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

Gives clear applicability context: works on the user's own collections and the 'Words not in a collection' bucket, and explicitly excludes curated Lingard collections as read-only. It does not, however, point to alternatives (e.g. preview_vocab_changes or commit_vocab_changes) or explain when to prefer them.

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 establish that this is a safe, idempotent read (readOnlyHint, idempotentHint, destructiveHint false), so the safety profile is covered. The description adds behavior beyond the annotations: it limits results to 'live' cards and warns that curated collections produce zero gaps, which prevents the agent from misreading an empty result as a bug.

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 with no filler: the core behavior comes first, followed by the one non-obvious caveat. Each sentence carries distinct information.

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

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

An output schema exists, so the description is rightly silent on return shape. However, for a 5-parameter tool with only 60% schema coverage, the description leaves the required targetLang unexplained, which is a real ambiguity for a gap check that is inherently language-specific.

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's field list (translation, POS, pronunciation, examples, image) maps onto the fields parameter, but the schema already documents that parameter thoroughly, including the array-not-string warning and the ANY-semantics. The required targetLang parameter is undocumented in both places, and limit and the two collection selectors are not mentioned at all, so the description does not compensate for the remaining 40% coverage gap.

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

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

The description gives a specific verb and resource: it returns live Lingard cards in a collection that lack requested fields, and it enumerates which fields (translation, POS, pronunciation, examples, image). That is clear enough for an agent to understand the tool's job. It does not name its natural counterpart, lingard_fill_missing_card_fields, so the distinction between diagnosing gaps and fixing them is left to inference.

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 use case is implied (a gap audit that would precede lingard_fill_missing_card_fields), but the description never explicitly states when to use this tool instead of its sibling. The caveat that a curated collection always reports zero gaps is a genuinely useful usage signal because it tells the agent when results are not meaningful.

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 read-only, idempotent, closed-world and non-destructive, so the bar is lower; the description nevertheless adds real behavior: the data is read live from the account, the collection list may be incomplete signalled by totals.truncated, and catalog collections are read-only. It doesn't cover auth/permission needs or response shape details, keeping it below a 5.

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

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

Front-loaded well with the core action in the first clause, and most sentences carry information (truncation, source semantics, fixity of counts). However, the closing sentence about catalog and unfiled titles 'the user did not choose; they belong to the same account all the same' is editorial padding that restates the source meanings.

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

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

An output schema exists, so return values needn't be explained, yet the description spends much of its length on payload semantics while omitting the one thing the schema doesn't document: the required targetLang argument. For a single-parameter context loader this leaves a real gap an agent must guess around.

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?

There is one required parameter, targetLang, with 0% schema description coverage, so the description carries the full burden — and it never mentions the parameter at all. An agent gets no guidance on whether targetLang is an ISO code, a display name, or what values are valid.

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

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

States a specific verb and resource ('Returns the user's current Lingard learning context, read live from their account') and enumerates the payload (profile, vocab totals, collections, card counts, missing-field stats). This clearly separates it from narrower siblings like lingard_get_vocab_collection or lingard_get_collection_gaps, though it never names an alternative explicitly.

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 line 'Earlier answers in the conversation may be out of date; this is the account as it stands now' implies the refresh/reload use case, which is genuine usage guidance. But there is no when-not-to-use statement and no routing to siblings such as lingard_get_collection_gaps or lingard_get_vocab_collection for narrower reads.

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 read-only, idempotent, closed-world behavior, so the description wisely spends its space on domain semantics instead: a paused collection gets no new words or reviews, is excluded from daily goals and reminders, yet still studies normally when opened in the app. That is genuinely useful context an agent could not derive from the schema.

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 verb and resource, then a compact explanation of pause effects and the returned identifiers. It is dense and information-rich, though the middle clause about app behavior is slightly long for its weight.

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

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

With an output schema present and a fully described single parameter, the description supplies exactly the missing piece: what 'on pause' means behaviorally and what identifiers each entry exposes. Nothing needed to call this tool correctly is absent.

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

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

Schema coverage is 100% and targetLang is documented with examples, so the schema carries the parameter burden. The description only echoes 'for one language' without adding format, defaults, or any nuance beyond what the schema states; baseline 3 applies.

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

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

States a specific verb (lists) plus the exact resource (collections and sources for one language) and the distinguishing attribute (which are on pause). It is immediately separable from lingard_set_learning_pauses and lingard_get_learning_context by its read-only, pause-focused scope.

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 mention that entries carry 'the exact uuid, bookKey, and title that pause changes take' implies this feeds the pause-setting workflow, but the sibling tool is never named and there is no explicit when/when-not guidance. Usage must be inferred from context rather than read directly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description adds real nuance: 'live' cards (implying archived or deleted cards are excluded) and the existence of curated collections plus the reading-time 'Words not in a collection' bucket. It does not discuss limit truncation behavior, but the safety and content profile is well 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?

Front-loads the core behavior in the first clause, then qualifies with the includeExamples case. Two sentences with little waste, though the second sentence is dense and could be split for scannability.

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?

Output schema and annotations carry the return shape and safety profile, so the description needn't explain them. But the required targetLang parameter is undocumented in both the schema and the description, and nothing is said about pagination/truncation when limit is set, leaving a visible gap for a 5-param read 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 80% and the schema already documents collectionUuid/collectionTitle precedence and includeExamples/limit. The description restates the selector pair and adds only the purpose of includeExamples ('editing examples starts from'); it says nothing about the required targetLang or about what limit does to results.

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

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

States a specific verb and resource (returns live cards from one Lingard vocabulary collection) and specifies the two selector modes plus the special 'Words not in a collection' bucket. This clearly separates it from siblings like lingard_get_collection_gaps or lingard_add_words_to_collection, which read gaps or mutate membership.

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?

Implies usage by describing the selectors and by noting includeExamples:true is what 'editing examples starts from', which hints at the follow-on workflow. However, it never says when to prefer this over lingard_get_collection_gaps or other read siblings, and offers no 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and closed-world behavior, so the safety profile is covered. The description adds useful context about 'live' profile data and duplicate avoidance, but says nothing about pagination, limits, or what 'live' implies operationally.

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?

A single well-formed sentence with the return contents front-loaded and the purpose appended. No filler and no repetition of the title.

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 output schema and annotations reduce the disclosure burden, and the description conveys the overall purpose. However, for a 7-parameter context-fetching tool with zero schema coverage and no sibling routing guidance, the definition leaves too much for the agent to infer about parameter behavior and tool selection.

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% across 7 parameters, so the description carries the full burden. It conceptually names level, topic, and collection context, but never explains targetLang, count, excludeLimit, or collectionUuid vs collectionTitle, leaving several parameters opaque.

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

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

States a specific verb ('Returns') and enumerates the resources returned: profile level, topic, collection context, and existing words, plus the purpose (suggesting level-appropriate non-duplicate cards). It does not differentiate itself from siblings like lingard_get_learning_context or lingard_get_collection_gaps, so an agent must infer the boundary.

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 use case is implied by 'the context for suggesting level-appropriate new cards that are not duplicates', but there is no explicit when-to-use guidance, no exclusions, and no named alternative among the many lingard_get_* siblings. Usage is inferable but not directed.

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

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

Annotations already cover the safety profile (readOnly, non-destructive), so the description's added value is elsewhere: it discloses that cards are validated exactly as on commit, and enumerates the completeness rules and the allowIncompleteCards escape hatch. It does not say whether the preview returns per-card error lists (though an output schema exists), so it stops short of full disclosure.

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

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

Five sentences, front-loaded with the no-write guarantee, then the validation contract. Dense but each sentence carries distinct information; the final 'form is not part of speech' sentence is the weakest because it largely restates the schema.

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 preview with an output schema, the description covers the essentials: it validates like a commit, lists completeness criteria, and documents the key language conventions. Remaining gaps are the merge/create flags and the explicit commit-tool relationship, which are secondary for a preview call.

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 top-level parameters (targetLang, change) carry no schema descriptions, and the description never explains change's structure, mergeMode, createIfMissing, or collectionUuid. It does compensate somewhat for the nested card rules (required fields, {} markers, article convention, form vs pos), but much of that repeats the already-rich nested card schema rather than adding new meaning.

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

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

States a specific verb and resource ('Previews a Lingard vocabulary collection/card change') and adds the crucial scope qualifier 'without writing to Firestore', which cleanly separates it from lingard_commit_vocab_changes. An agent can select it without opening the schema.

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

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

The 'without writing to Firestore' phrasing implies this is the dry-run step before a commit, but the sibling lingard_commit_vocab_changes is never named and no explicit 'use this before X' instruction is given. Usage is inferable rather than stated.

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, idempotentHint=true, destructiveHint=false), the description adds real behavioral context: paused items yield no words to automatic 'Now learning' sessions and are excluded from goals/reminders, yet still studyable when opened in the app, and lists are ignored under 'resume_all'. It never states whether pausing is reversible through the same call, though 'resume' is implied to be the inverse.

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?

Purpose is front-loaded in the first clause and every sentence carries information (actions, identifier formats, side effects, commit). It is a single dense paragraph that runs long; the action semantics could have been broken into a short list for faster scanning, but nothing is redundant.

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 mutation tool with an output schema present, the description covers the full decision surface: which action to pick, how to identify targets, what pausing actually does, and that commit gates writes vs preview. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 80%, so the baseline would be 3, but the description compensates further: it specifies collections are identified by uuid or exact title and sources by bookKey or exact title, clarifies the four enum values' semantics, and restates commit's preview behavior. This adds identifiers and edge-case meaning beyond the schema strings.

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 concrete verb+resource ('Puts collections and sources on pause or takes them off it, for one language') and enumerates the exact effects. It also implicitly distinguishes itself from the sibling getter by noting items are named 'as the learning-pause list reports them', so an agent can tell this mutator from lingard_get_learning_pauses without opening a schema.

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

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

It gives worked use-case examples ('study only my Travel collection this week', 'resume everything') and then defines what each action value means relative to the others, including that 'only' pauses everything not listed and 'resume_all' ignores the lists. The preview-vs-write condition via commit is stated explicitly, leaving no ambiguity about when to use which mode.

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 flag destructiveHint=true and idempotentHint=true; the description adds real value by bounding the destruction (only the translation line is rewritten), clarifying that empty translations are a valid state rather than an error, and describing the dry-run preview 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?

Front-loads the scope constraint before the mechanics, and every sentence carries information (what is preserved, what is mutated, ordering rule, commit semantics). Slightly dense but no filler.

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

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

With an output schema present and rich annotations, the description covers mutation scope, error tolerance, and preview behavior. The only meaningful gap is the undocumented `targetLang` parameter, which is neither described here nor in the schema.

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

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

Schema coverage is 80%, and the description supplements it with the crucial positional contract for `translations`: entry N maps to example N, shorter lists leave the rest untouched, and {"index":2,"t":"…"} patches a single entry. `targetLang` remains unexplained in both schema and 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?

States a precise verb and scope: it rewrites only the translation line of existing examples while leaving sentence, {} highlights, and audio/typing markers untouched. This cleanly separates it from siblings like lingard_fill_missing_card_fields that touch other fields.

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

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

Explicitly explains that translations must be built from the card's current examples (read via a collection fetch with includeExamples:true) and that commit=true writes while omitting it yields a preview. It doesn't name a sibling alternative, so it stops short of a 5.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuine context beyond that: results are read from Firestore at call time, i.e., fresh/live rather than cached. It does not disclose result limits, ordering, or what happens with an empty query or unmatched terms, which matters for a tool with zero required parameters.

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, both front-loaded: the verb and scope lead, and the freshness caveat follows. The enumerated domain list is long but each item is a real capability, so it earns its space. Slightly list-heavy, but no filler sentences or marketing language.

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

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

An output schema exists and annotations are rich, so the description need not explain return values or safety. What it does cover — searchable domains and live-data freshness — is the right material. The missing piece is routing: with 14 siblings including several near-overlapping getters, the description should say when this broad search beats a targeted sibling call, and it does not.

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. The description adds nothing about parameter behavior — it does not mention the q/query alias pair or explain how query intent maps onto the enumerated domains. It neither helps nor compensates 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?

States a specific verb (Searches) and resource (the user's live Lingard account), and enumerates the searchable domains: vocabulary, learning context, profile, totals, collections, saved words, flashcards, missing fields. This is far more than a restatement of the name. However, it does not differentiate itself from siblings that cover the same ground (e.g., lingard_get_learning_context, lingard_get_vocab_collection), so the agent cannot tell from the description alone whether this generic tool or a specific one is correct.

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 when-to-use or when-not-to-use guidance, and no named alternatives. The enumeration of searchable domains implies broad usage, but several siblings (lingard_get_learning_context, lingard_get_vocab_collection) appear to overlap directly, and nothing tells the agent which to prefer. The agent must infer routing from sibling names it may not have read.

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