layers

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

With no annotations supplied, the description carries the full behavioral burden, and it does disclose real substance: the 'Background' layer is the pinned bottom layer that fills the canvas and is updated differently (color/visible only), reference layers are tracing underlays excluded from export, and opacity is bounded 0-1. It omits whether clear/delete are permanent or undoable, what the defaults are when layer is omitted, and what list returns — significant gaps for a mutation-heavy tool with zero annotation coverage.

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?

The action list is correctly front-loaded, so the first clause does the most important work. However, the parenthetical that follows is a single dense run-on bundling the Background rule, blend enum, reference semantics, locked, and index — an agent must parse a long comma-spliced fragment to extract each fact.

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 10-parameter, 6-action tool with no annotations and no output schema, the description covers the most surprising behaviors (Background pinning, reference exclusion from export, blend vocabulary) but never states the action-to-parameter mapping, what list returns, or the destructive consequences of clear/delete. Adequate to start, short of what the complexity warrants.

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 only 20%, so the description must compensate, and it does for several parameters: it supplies the full valid blend-mode enumeration (the schema types blend as a bare string with no enum), defines reference as a tracing underlay excluded from export, and bounds opacity to 0-1. It leaves 'name' (new name vs. layer lookup?) and 'index' (reorder vs. selector) unexplained, and never maps which parameters apply to which action.

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 ('Manage layers') and then enumerates the exact operations: list, add, update, select, clear, delete — matching the action enum one-for-one. It is clearly distinguishable from siblings like board, draw, or edit_items. It stops short of an explicit sibling differentiation statement, but the enumeration makes the tool's remit unambiguous.

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 action list implicitly tells the agent which operation to pick, but there is no when-to-use vs when-not guidance, no prerequisites, and no steering toward sibling tools (e.g. whether layer work belongs here versus board or drawing_space). Usage is inferable from the action vocabulary rather than stated.

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