herdr_controller_takeover

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

With no annotations, the description carries the burden, and it does convey that this is a conditional transfer of an expired lease and that a durable authority plus predecessor lease are required. It does not disclose the side effects on the previous identity/lease, error behavior, or whether the operation is reversible, which matters for a takeover-style mutation.

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 a single dense sentence with the core action and guardrails front-loaded; no filler. The word 'done' is terse and the sentence is long, but it remains economical.

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?

A takeover operation with five parameters, four required, no annotations, and no output schema needs more lifecycle context: when to prefer it over controller_resume/renew, what response confirms takeover, and what happens to the predecessor lease. The description gives preconditions but leaves these gaps.

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 description maps expected_predecessor_lease_id ('expected predecessor lease'), controller_id ('expired controller lease'), and the authority parameters ('durable authority'). With 0% schema coverage it still leaves ttl_seconds unexplained and does not clarify the relationship between authority_ref and authority_sha256.

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 names a specific action ('transfer'), a specific resource ('expired controller lease'), and a target ('this Herdr pane'), then narrows it with explicit conditions ('only when previous identity is missing, done, or blocked'). This makes the tool distinct from typical acquire/renew/release controller operations even without reading 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 gives an explicit condition of applicability: only when the predecessor identity is missing/done/blocked and the lease has expired. It implies not to use when a healthy/active predecessor exists, but it does not name alternatives such as herdr_controller_resume or herdr_controller_renew.

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