athena_deployment_cutover_hold

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

With no annotations, the description must carry the behavioral disclosure burden. It does a good job enumerating what the result cannot do ('cannot deploy, resolve secrets, mutate state, stop/start a writer, or activate traffic'), which conveys a safety-focused, non-destructive operation. Yet it omits what the tool does beyond 'bind', such as persistence, return value, permissions, idempotency, or failure modes, so it meets the minimum but is not rich.

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, front-loaded with the action and target. Every clause adds information about inputs or behavioral limits. It is dense and jargon-heavy, but no words are wasted, earning a 4 rather than a 5 due to the high cognitive load.

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?

This is a complex tool with no annotations, no output schema, and 0% schema coverage. The description provides only a high-level binding action and a negative list, without explaining what the returned result is, how the hold is represented or verified, or what prerequisites must be satisfied beyond the input types. An agent would struggle to know if the invocation succeeded or how to use the result, making the description incomplete for this complexity.

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 0%, so the description must compensate. It names all four parameters and adds meaningful constraints: the plan must be PLAN_ONLY, the canary witness must be checksum-valid and isolated, quiescence observation is 'supplied', and cutover_authority_ref appears as an 'authority reference'. This goes beyond the bare schema, though it still doesn't describe the structure of the nested objects.

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 uses a specific verb ('Bind') and names the target resource ('ATHENA.CUTOVER.HOLD.1'), distinguishing it from sibling tools like verify_cutover_hold. However, the term 'bind' is somewhat abstract, and the listed input qualifiers ('PLAN_ONLY activation plan', 'checksum-valid isolated canary witness') may not be immediately clear to an unfamiliar agent, so it stops short of a 5.

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 implies usage context by listing the specific inputs required (plan, canary witness, quiescence observation, authority reference), suggesting this tool is used when such validated artifacts are available to place a cutover on hold. It also hints at a safe, non-deploying purpose via the limitation list. However, there is no explicit 'when to use', no mention of alternatives, and no exclusions, so it only earns a 3.

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