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

Annotations already signal idempotentHint and destructiveHint false, and the description reinforces this with dedupe behavior: 'Words the user already have are skipped, not duplicated.' It also discloses the side effect of entering the spaced-repetition schedule and summarizes what the return value contains, all beyond the structured annotations.

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

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

The description is dense but every sentence earns its place: core action, when to use, parameter orientation, dedupe behavior, return summary, and sibling-tool routing. The most important information is front-loaded.

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

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

For a 3-parameter tool with no output schema, the description covers usage triggers, language-pair semantics, duplicate handling, return value contents, and the correct alternative tool. The enum values and constraints are already in the schema, so no critical guidance is missing.

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

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

Schema coverage is 67%, and the description compensates by giving field-level guidance: 'Put each word in term in the language being learned and its meaning in translation,' and it clarifies that example is optional and should be added 'when it helps.' This meaningfully exceeds what the schema alone provides.

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

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

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

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

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

It gives a clear trigger: 'Use when the user asks to save or add words, for example from a text you discussed.' It also provides an explicit alternative and exclusion: when the user wants a deck for Anki, Quizlet, Mochi, or Brainscape, use save_deck instead.

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