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.