Restart, redeploy or remove app instances

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

With no annotations the description carries the full load and does well: it discloses that hard=true destroys data, that remove does not truly delete (the network re-spawns it), and that the owner key is required for authorization. It omits any statement about disruption/gracefulness of restart, reversibility, or the shape of the response, which keeps it short of a 5.

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?

One dense, front-loaded paragraph keyed by action name, then scope, then auth. Every clause carries a distinct fact and nothing is repeated from the schema or title.

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 an unannotated mutation tool with no output schema and 5 params, the description covers action semantics, scope, data-destruction, authorization and the correct sibling for stopping the app. It could still say what is returned or whether the operation is awaited, but nothing needed for correct invocation is missing.

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 only 40%, but the description compensates by explaining what each action value means, the data-loss consequence of hard, and that scope is 'one node (nodeIp) or every node running the app (global)'. The remaining params (name) are self-evident; the nodeIp description in the schema is actually slightly richer than the prose, so no gap remains.

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 set (restart/redeploy/remove) against a specific resource (app containers/nodes) and even disambiguates the confusing case by naming the sibling flux_cancel_app. An agent can distinguish it from flux_cancel_app, flux_deploy_app and flux_get_app without opening any 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 per-action conditions ('redeploy: pulls the image again... hard=true also wipes data') and an explicit alternative for the wrong choice: 'remove... the registration stays and the network re-spawns it elsewhere, so use flux_cancel_app to stop paying.' That is an explicit when-not plus named alternative.

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