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

The description adds behavioral context beyond the annotations: it discloses deduplication ('Words the user already has are skipped, not duplicated') which aligns with the idempotentHint, and states the return summary ('Returns how many were added, already saved, or invalid'). This complements the annotations without contradicting them.

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 tight, front-loaded paragraph: intent first, then usage context, field guidance, dedup behavior, and return value. Every sentence adds value and there is no redundancy or filler.

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

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

For a save operation with 3 top-level and 4 nested fields, the description covers the key semantics (language pair, field meanings, dedup, return counts) so an agent can construct a correct call. Minor omissions like character limits are already in the schema, and the output is adequately described for a tool without an output 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?

With schema coverage at 67%, the description compensates for the missing 'words' schema description by explaining meaning of 'term', 'translation', and 'example'. It also reinforces the roles of learningLanguage and translationLanguage ('the language being learned' and 'its meaning'), adding clarity beyond the schema's short descriptions.

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

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

The description states a specific verb ('saves') and resource ('new words to the user's NextLang vocabulary for one language pair'), explicitly linking to the spaced-repetition schedule. This clearly distinguishes it from siblings such as search_vocabulary or list_due_words, leaving no ambiguity about its function.

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 provides an explicit trigger condition ('Use when the user asks to save or add words, for example from a text you discussed') and gives field-level guidance ('Put each word in 'term'...'). While it doesn't name alternative tools for when this shouldn't be used, the context is clear enough for an agent to select it appropriately.

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