Control area entities by domain

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false), and the description goes well beyond them: it explains that the action is a validated enum (turn_on/turn_off/toggle), that an unchecked value could reach an arbitrary service, that ValueError is raised on bad action, and that an invalid domain surfaces the underlying HA HTTP error. Error modes and validation behavior are exactly the kind of context structured fields cannot carry.

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 is front-loaded in sentence one and the labeled Use when / Not for / Errors / Limits blocks are easy to scan. Slightly verbose: the ADR-0006 parenthetical and the 'Returns' line restate what the output schema already provides, so a little text does not earn its place.

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 three-parameter mutation tool this covers everything an agent needs: selection criteria, the alternative tool, the service-dispatch mechanism, validation failures, and upstream HTTP failure behavior. Return values are already covered by the output schema, so the extra 'Returns' line is a harmless redundancy rather than a 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?

Schema coverage is 100%, so the baseline is 3, but the description adds compositional meaning the schema does not: `domain` and `action` are combined into the `<domain>.<action>` service name and `area_id` is passed as the target payload, so the agent understands the parameters jointly rather than as three independent fields. It does not explain the `light` default beyond the schema text.

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 first sentence states a specific verb (turn on/off/toggle) and a precise resource scope (every entity of one domain within an area). It also discloses the underlying mechanism — dispatching `<domain>.<action>` with an area target — which distinguishes it unambiguously from entity-level and list-level siblings.

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?

It contains an explicit 'Use when' clause ('controlling a whole area by domain, e.g. all lights in a room') and an explicit 'Not for' clause naming the alternative (`entities_bulk_control`) for explicit entity_id lists across areas. Nothing about tool selection is left to inference.

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