Wait for state changes

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds substantial behavior: it is a bounded long-poll ('Wait up to wait_seconds'), the first call returns all current states while later calls return only changes, it only works through VomeHome, and the key needs ha:read on the home. That is exactly the kind of auth/mechanism context annotations do not 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?

Three dense sentences, front-loaded with purpose before mechanism and constraints, with no filler. It is slightly compressed in the final sentence (VomeHome + ha:read), but every sentence earns 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 stateful long-poll tool with no output schema, the description covers the mechanism, continuation, auth, and transport constraint. Minor gaps remain around timeout return behavior (e.g., empty vs partial on expiry), but the safety profile is fully covered by annotations.

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 the round-trip workflow for cursor ('The first call returns every entity's current state; pass back the returned cursor') that goes beyond the schema's one-line note. It also frames wait_seconds as an upper bound.

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 states a specific verb and resource ('Wait ... for any of these entities to change, and return what changed') and clearly differentiates itself from polling siblings like ha_get_state/ha_get_history by emphasizing the wait semantics. An agent can tell what this does without opening the schema.

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 names the use case ('for a client showing live states (a dashboard pane)') and the alternative it replaces ('instead of polling'), plus the continuation rule for the cursor. The condition that selects this tool versus polling is explicit.

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