Draw a picture on the display

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

With no annotations, the description carries the full burden and does so well: it discloses the timed display window, auto-centring, automatic scale reduction if the image would not fit, per-character colour semantics, and that the result returns read_display showing actual output. It does not describe error behaviour for oversized/malformed rows or whether the call blocks for `seconds`.

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?

Single dense paragraph with the primary action and timing front-loaded, then constraints by module type, then rendering rules. Every clause carries information, though the colour-letter enumeration is bulky and could be tightened without losing meaning.

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 a 5-parameter tool with a nested palette object and no output schema, the description covers what the tool does, how rows map to pixels and colours, module-specific behaviour, scaling and fit rules, and that the return is equivalent to read_display. An agent has everything needed to call it 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%, but the description still adds substantial meaning beyond it: it explains the character-to-colour mapping, which characters are dark, that palette letters add or override colours, that `panel` only matters on the monochrome SSD1306, and how `scale` interacts with the module resolution. That is real semantic value layered on top of the schema.

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+resource+lifecycle: 'Show a picture on the Face Display module for `seconds`, then return to the face.' An agent immediately understands this is a multi-row pixel-art draw with a timed revert. It stops short of naming how it differs from nearby siblings like display_text or set_display, so the distinction is inferable rather than stated.

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?

Usage is implied by the 'one string per pixel row' and resolution constraints, and it points to read_display for module sizes. However, it never states when to prefer this over display_text, set_display, or display_text-like siblings, nor what happens when the picture exceeds the module. No explicit when/when-not guidance.

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