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

Annotations only mark readOnlyHint=true, but the description adds substantial behavioral context: error detection returns incorrect_cells instead of a hint, two-board mode validates user entries, single-board mode cannot perform error checking, and every response includes solve_url plus tutorial_links on success. This goes far beyond the annotation.

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 tightly organized with mode headings and purposeful bullets. Every section earns its place, the core purpose is in the first sentence, and the return contract is stated compactly at the end.

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 no output schema, the description properly discloses the return shape: success returns technique, explanation, action, and tutorial_links, while error mode returns incorrect_cells and message. It also covers the two invocation contexts and the always-present solve_url, so an agent has everything needed to call and interpret the tool 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?

Although the input schema already covers both parameters fully, the description enriches their meaning: puzzle is the original clue string in two-board mode but becomes the user's full board in single-board mode, and progress must preserve clue digits while omission yields the first hint. This is exactly the kind of mode-dependent semantic nuance that the schema alone cannot convey.

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 opens with a specific verb and resource: 'Get the next logical solving step for a sudoku puzzle.' It clearly distinguishes the tool's coaching role from siblings by explaining step-by-step hints, and it even separates two operational modes, making its 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 explicit when-to-use guidance for both modes: 'use when you know both the original clue grid and the user's current work' and 'use when the original clue grid is unknown.' It also states the coaching intent, but it does not explicitly name sibling tools like solve_sudoku or check_progress as alternatives, so the when-not-to-use guidance is slightly implicit.

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