read_pixels

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

With no annotations, the description carries the full behavioral burden, yet it only discloses the 1024-pixel size limit and row-major ordering. It does not say what happens when x/y are out of canvas bounds, whether the request is truncated or rejected above the cap, whether hidden or non-active layers are read, or how colour values are returned (hex vs channel tuple).

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?

A single short sentence with no waste, and the most important constraint (the pixel cap) is packed in early. It is efficiently written, though the terseness borders on under-specification for a five-parameter tool.

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 0% schema coverage, no annotations, and no output schema, the description omits the essentials: coordinate origin, layer selection semantics, out-of-bounds behaviour, and the format of returned colour values. It is too thin relative to the tool's complexity.

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 description coverage is 0% across 5 parameters, so the description must compensate. 'Small block' and 'max 1024 pixels' implies width/height semantics, but x and y are never explained (top-left origin? canvas coordinates?), and the 'layer' parameter with default null is completely undiscussed, including whether null means the active layer.

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 names the resource ('exact colours of a small block') and adds scope ('max 1024 pixels') plus output ordering ('rows top to bottom'), so an agent can tell it reads raw pixel data rather than rendered previews. However, it is a noun phrase with no explicit verb, and it never distinguishes itself from nearby siblings such as sample_color or canvas_snapshot.

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?

There is no when-to-use guidance at all: no statement of when to prefer this over sample_color (single-point sampling) or canvas_snapshot (full/visual capture), and no prerequisites mentioned. The 1024-pixel cap hints that this is for small regions only, but the agent must infer that this tool is inappropriate for large regions or visual inspection.

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