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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the description is free to add the non-obvious parts: a solver validates each puzzle has exactly one solution before printing, and the PDF layout (1/2/4 per page, Letter or A4, optional title and name line, answer pages) is disclosed. It stops short of describing the returned file reference or how long generation takes, which would round it out.

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?

Front-loaded with the trigger phrase, then constraints, then the puzzles[]/count rule, then defaults, then the negative boundary. Dense and nearly every sentence carries distinct information, though the run-on length and parenthetical packed into the first sentence make it slightly harder to scan than it needs to be.

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?

For an 11-parameter, fully-defaulted generator with an output schema and rich annotations, the description covers the trigger, the grid constraints, the two configuration modes, accepted operation spellings, validation behavior, layout options, and the full default state. There is nothing an agent needs to know to call this correctly that 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?

With 100% schema coverage the baseline is 3, and the description earns above that by explaining the key interaction the schema can't: use puzzles[] when puzzles differ, use count plus size/operations/difficulty for a uniform set, and operations accepts either signs or words ('add only', 'all four', 'no division'). It also restates the default configuration, which helps an agent decide whether to pass anything at all.

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 ('generate printable math cage puzzles') and immediately disambiguates the artifact: a PDF with an answer key, grids from 4x4 to 9x9 using 1..N once per row/column, with cages showing a target and sign. An agent knows exactly what this produces without opening the schema.

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?

Opens with an explicit trigger ('Use this when the user wants printable math cage puzzles... for a class') and closes with exclusions: it does not solve a puzzle from a photo and does not make grids larger than 9x9. No sibling tools exist to route against, so the when/when-not coverage is adequate on its own.

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