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

Annotations only state readOnlyHint and idempotentHint. The description goes far beyond by detailing connection-based blocking, the meaning of each return field (blocked, missingRiddles, resolveByAddingUUIDs, etc.), the deduplication of addUUIDs, the intersection logic of projects, and the chaining of dependencies. It discloses conditional behavior (e.g., a Riddle blocked alone may be movable in a larger set) and outlines the iterative process. No contradiction with annotations; it complements 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 lengthy but front-loaded with the core purpose and usage. It is structured into flowing prose covering the major aspects: purpose, dependency logic, return field breakdown, and usage pattern. While it could benefit from bullet points for the return structure, the density is warranted given the tool's complexity. Every major element is covered without redundancy, so it earns a 4 rather than a 3.

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?

This tool has no output schema, so the description must fully explain the return value; it does so in great detail, naming every field and its meaning. It also covers edge cases (connections, inaccessible projects, blocked-by-siblings) and provides a clear usage algorithm. For a complex check tool with a rich response, nothing essential is missing, making it contextually complete.

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 covers both parameters (UUID and UUIDs) with descriptions, so the baseline is 3. The description adds semantic depth: it explains that the answer depends on the whole set, instructs to 'Pass exactly the UUID/UUIDs you intend to hand to riddle_move', and clarifies that different sets yield different outcomes. This goes beyond simple parameter typing and provides context for effective usage, justifying a 4.

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 explicitly states the tool 'Checks, without changing anything, whether a set of Riddles can be moved and which projects they can be moved to'. This is a specific verb (check), resource (Riddles), and scope (set-based). It also differentiates itself from the sibling riddle_move by referencing 'the same check riddle_move runs before it moves anything,' making the purpose unambiguous.

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?

The description gives direct usage guidance: 'Use this before riddle_move whenever the Riddles were not all created by you, or to explain to the user why a move is not possible.' It also implicitly tells when not to use it (when you're ready to execute the move) and explains the iterative pattern ('add UUIDs and check again, repeating until canMoveAll is true'). This is explicit and actionable.

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