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

Despite annotations already declaring this a destructive, non-read-only, idempotent write, the description adds substantial behavioral context beyond them: a level counts as known for about a month along with all lower steps, the word leaves quizzes on those steps and returns once for a check in about three weeks, and 'none' sends the word back to practice. It also discloses output-side handling of terms not found in the vocabulary ('unknown'), which is exactly the kind of side-effect detail an agent needs.

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?

All the content earns its place, but the structure is a dense run-on that embeds the parameter definition mid-sentence and mixes semantics, side effects, and edge cases with semicolons. The core action is front-loaded, yet the level definitions and timing rules are hard to scan. Valuable information delivered in a suboptimal layout.

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 one-parameter mutating tool with annotations covering the safety profile and no output schema, the description is nearly complete: it documents the parameter, the side effects on quizzes and repetition timing, and unknown-term handling. It does not state what happens on exceeding the 200-item cap or what the call returns, but given the annotations and absence of an output schema these gaps are minor.

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% and the single 'items' parameter is an untyped array of open objects, so the description carries the full burden — and it does. It specifies the item shape, the enum values (none|recognize|recall|listen|say), the max count (up to 200), and defines each level (recognize = understands, recall = translates into it, listen = understands by ear, say = says from memory, none = does not know it). This fully compensates for the empty 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 states a specific verb and resource: it records how well the user knows words of the active language, driven by the user's own answers. It also distinguishes itself from the sibling mark_known by noting it applies 'the same marks as mark_known with skills,' so an agent can differentiate the two. It stops short of a crisp one-line statement of purpose because the details of levels and timing are woven in before the core action is fully framed.

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?

Usage is implied: this is the tool to call when you have the user's self-reported knowledge levels for a batch of terms. The mention of 'the same marks as mark_known with skills' signals a relationship to that sibling but does not state when to choose calibrate over mark_known, nor any prerequisite (e.g., an active language or session). No explicit when/when-not guidance is given.

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