pcb_set_layer_color

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

With no annotations, the description carries the full burden and does well: it discloses the silent-failure mode (a refused assignment raises nothing), that the write is read back before success is reported, and that colour is installation-scoped rather than saved with the file. That is exactly the kind of beyond-schema behaviour an agent needs. It stops short of stating what happens with an unknown or non-existent layer name.

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 one-line purpose, then progressively deeper context, then Args. No filler sentences; even the internal-encoding note earns its place by telling the caller not to pre-swap bytes. The Returns block is mildly redundant against the output schema but does not bloat the text.

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?

An output schema exists, so return values need no explanation, and the description still names the returned keys. Combined with the format, verification and persistence semantics, an agent has enough to call this correctly. The remaining gap is error/validation behaviour for a bad layer name or bad hex string.

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% — the properties carry only bare titles — so the description must compensate, and it does: it gives the layer naming convention with concrete examples ("TopOverlay", "Mechanical13") and specifies the colour format as "#RRGGBB" plus the fact that the TColor byte-reversal is handled server-side. Neither parameter's failure mode (invalid layer, malformed hex) is described.

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?

Opens with a specific verb+resource: "Recolour one layer." That is unambiguous and an agent can immediately tell it is a per-layer display mutation. It does not distinguish itself from nearby siblings such as pcb_set_layer_visibility, pcb_modify_layer or pcb_get_layer_display, which keeps it out of the top band.

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 only implied: the note that colour is a display setting rather than a board property tells the agent this is cosmetic, non-geometric configuration, which is useful framing. But there is no explicit when-to-use, when-not-to-use, or named alternative (pcb_modify_layer is the obvious candidate), so the agent must infer selection.

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