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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this with 'without changing anything'. But the description goes far beyond annotations, disclosing how blocking propagates along connections, how 'resolvable' is shared among connected Riddles, that connections chain, and what an empty 'missingUUIDs' means. This is rich behavioral context that the annotations alone could never convey.

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 long, but every section earns its place: purpose and scoping first, then behavior, then the return object, then a resolution loop, and finally when-to-use. It is dense rather than padded. A slightly more structured layout (e.g., bullets for the return fields) would improve scanability, but this does not detract from the information value.

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?

The tool has complex return semantics and no output schema, so the description carries the full burden of documenting what the call returns — and it does comprehensively: every return key (canMoveAll, movable, blocked, addUUIDs, canMoveToPersonal, projects) is explained with its meaning and edge cases. Given the annotation context and schema coverage, an agent has everything needed to call this tool and interpret its result correctly.

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 schema already documents both parameters fully (UUID vs UUIDs, format, max 100). The description adds genuine semantic value beyond the schema by explaining that the answer depends on the whole set and that the passed UUIDs must be exactly what would be handed to riddle_move, which meaningfully informs how the agent should choose values.

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 and resource: it 'Checks' whether 'a set of Riddles can be moved and which projects they can be moved to'. It also explicitly distinguishes itself from the sibling riddle_move by noting it performs 'the same check riddle_move runs before it moves anything', so an agent can immediately tell them apart.

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 explicit when-to-use 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 names the sibling tool and provides a concrete usage precondition: 'Pass exactly the UUID/UUIDs you intend to hand to riddle_move.' It also explains the iterative pattern of checking, adding UUIDs, and re-checking.

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