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

Annotations already declare this as a non-readOnly, non-destructive write, so the safety bar is partly covered. The description adds real behavioral context beyond that: duplicate cards are silently skipped, and the 'back' field must use the user's ui_lang pulled from today/profile. It stops short of describing the response or any rate/limit 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?

The JSON example is front-loaded and is exactly the kind of concrete artifact an agent needs for an unspecified object array, with the dedup and entry-rule notes following compactly. No sentence is filler given the 0% schema coverage it has to offset.

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 write tool with an untyped schema and no output schema, the description covers payload shape, dedup behavior, and field-language rules, which is most of what is needed. Minor gaps remain: no batch-size limits and no description of the creation result/return, though the absence of an output schema lowers that expectation.

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 0% and the single parameter is an untyped array of loosely-typed objects, so the description carries the full burden and largely does so – it enumerates the fields (front, back, kind, example_front, example_back, tags) and gives semantics for each, including the 'word|phrase' enum for kind. It lacks per-field type/nullability detail, but compensates well for the schema 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 ('Add cards', with the title clarifying flashcards) and spells out the exact payload shape, so the agent knows it is creating vocabulary cards. It does not, however, distinguish itself from the sibling vocab_add, leaving the agent to guess which of the two add-style tools to pick.

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 implied usage via the entry-rule hint ('one card is one word in its dictionary form ... or one whole ready phrase') and an external pointer ('entry rules: docs("vocab")'), plus the useful 'Duplicates are skipped' behavior. But there is no explicit when-to-use vs when-not guidance relative to alternatives like vocab_add or mark_known.

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