analyze_games

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

With no annotations, the description carries the burden and does well: it discloses the batch/short-call cost model, the continuation pattern, and that it 'Returns progress counts only' rather than analysis output. It omits whether motif tagging persists data or what permissions/engine resources are required.

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?

Four short sentences, front-loaded with the core action, then behavior and prerequisite. No filler, though the 'call again to continue' fragment is slightly under-integrated.

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?

No output schema and no annotations, yet the description covers return shape, batching, continuation, and ordering. Only missing pieces are persistence/permission details for the motif tagging it performs.

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%, so the schema names batch_size and max_seconds without explaining them. The description hints at their meaning ('works in small batches so one call stays fast') but never maps that to the parameters or mentions defaults (25, 45).

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?

States a specific verb (analyse with Stockfish), the exact resource scope (not-yet-analysed games, newest first), and a secondary effect (tagging costly moves with motifs). This clearly separates it from sync_games (downloads) and tag_motifs (tagging).

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?

Gives an explicit prerequisite ('Use sync_games first to download games') and an iteration contract ('call again to continue'), plus a pointer to tag_motifs for the motif side. It stops short of stating when not to use it, but the ordering constraint is clear.

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