pcb_get_layer_display

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

With no annotations, the description carries the burden and mostly does: it scopes the result to the active board, declares the exact return keys, and warns that Altium stores colour as a byte-reversed Windows TColor so a reversal yields a plausible wrong colour rather than an error. That is a genuine behavioral trap disclosed proactively. It never explicitly states read-only/no side effects or pagination/scale limits, which keeps it at 4.

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: the one-line purpose comes first, then coverage, then the critical gotcha, then returns. Every sentence carries information. Minor waste in the explicit 'Returns: Dict with layers, count and visible_count' block, which restates the output schema and could be dropped.

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 zero-argument read on the active board with an output schema available, the description supplies everything needed to call it correctly and interpret results: scope, layer coverage, field meanings, and the colour-encoding pitfall. The returns section is redundant but harmless given the schema, not a completeness gap.

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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies by rule. The description's field-level explanations (layer id, name, visible, color/color_hex) describe outputs rather than inputs, which is appropriate here.

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 concrete verb and resource — visibility and colour for every layer on the active board — and enumerates the layer families covered (signal, plane, mechanical, mask, paste, silk, keepout, multilayer). It also lists the per-entry fields, so the agent knows exactly what it gets without opening the schema. Clearly distinct from the setters (pcb_set_layer_color, pcb_set_layer_visibility) and from pcb_get_layer_stackup.

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 sentence 'Read this before recolouring' gives an explicit when-to-use trigger tied to a downstream action, which is unusually actionable. It does not name the alternative/sibling it feeds into (pcb_set_layer_color) or state exclusions, so it stops short of the 5 bar.

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