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

Beyond the readOnly/openWorld annotations, the description discloses privacy handling ('Player identities are removed') and a concrete rate-limit remedy ('after 429 wait 60 seconds'), plus the 1-50 range bound. Those are exactly the operational facts annotations cannot convey; it stops short of describing ordering or pagination 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?

Three compact clauses with the core behavior and the count range front-loaded, then filters, then caveats about theme enumeration and rate limits. The mid-sentence note that the source schema publishes no finite theme list is slightly meta but earns its place by capping expectations on 'angle'.

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?

With an output schema present, the description need not document return values, and it covers the remaining gaps an agent would care about: valid count range, exact-source filtering semantics, anonymization, the absence of a finite theme list, and the 429 remedy. Nothing needed to call it correctly 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 100%, so the baseline is 3. The clause 'optional difficulty and side-to-move filters use the source values' adds a little meaning by signaling that difficulty is matched exactly against source values rather than normalized, but the other parameters gain nothing beyond the schema text.

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 gives a specific verb and resource ('Returns 1-50 public puzzles') along with the key scoping input ('open-ended theme angle'), which is clearly distinct from a single-puzzle fetch. It does not, however, differentiate itself from similarly named siblings such as lichess_puzzle_many or lichess_puzzle_themes, so an agent must infer which batch variant 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?

Usage is implied rather than stated: needing 1-50 puzzles for a theme is the evident trigger, and 'open-ended theme angle' implies you do not need a fixed theme list. There is no explicit when-not guidance or named alternative for single-puzzle or theme-list lookups, leaving selection between siblings to inference.

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