herdr_agent_wait_settled

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

No annotations are provided, so the description carries the full burden. It discloses that the tool waits for specific states and returns state plus visible output, and mentions stale-state handling via after_seq. However, it does not describe timeout behavior, potential blocking duration, error handling, or any side effects. This is adequate but not comprehensive for a waiting tool with timeout_ms available.

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 description is two sentences and every word earns its place. The core action and state conditions are front-loaded, and the after_seq note adds critical behavioral context without redundancy. It is concise, well-structured, and immediately scannable.

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 tool with no output schema, the description hints at return values ('state and visible output') but does not detail the structure. It also omits timeout behavior, even though timeout_ms is a parameter, and does not explain read_lines. Given the complexity of a waiting operation, more context would be needed for a complete picture, but the description covers the essential purpose and a key parameter.

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 25%, so the description must compensate for the undocumented parameters. It only explains after_seq (useful for avoiding stale states) but provides no explanation for read_lines or timeout_ms. Since two of the four parameters lack semantic context in both schema and description, the description is insufficient.

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 clearly states the verb 'wait' and the resource 'agent', and specifies the exact states it waits for (idle, done, or blocked) and what it returns (state and visible output). This distinguishes it from generic wait tools, though it does not explicitly contrast with sibling wait tools like herdr_agent_wait, which is a minor gap.

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 description provides guidance on using the after_seq parameter to avoid stale terminal states, which is helpful. However, it does not explicitly state when to prefer this tool over alternatives such as herdr_agent_wait or herdr_wait_output, nor does it mention conditions when this tool should not be used. Usage context is implied but not fully explicit.

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