aua_goal_decide

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

The annotations only flag that this mutates state, acts in an open world, and is not idempotent. The description adds far more: the tool re-reads the UI, discards the choice and returns previous_choice_stale=true if the screen changed, executes the candidate only once, then checks the effect and returns the next decision, completion or handoff. It also documents token lifetime rules and the fact that an unknown option ID keeps the token while any other outcome consumes it.

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?

It is dense and front-loaded: the first clause identifies the step and the required input, and the remaining sentences add failure modes, the return or handoff behavior, and timing constraints. Nothing is filler, but several sentences are run-on, and the jump from stale-choice handling to token lifetime forces careful reading.

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 two-parameter tool with no output schema, the description covers everything needed to call it safely: input provenance, staleness handling, the possible outcomes (next decision, completion, handoff), and the fact that timeout_seconds counts device time only rather than host thinking time.

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?

Because the schema has no descriptions at all, the description carries the full burden. It maps token to the one-time token from the latest decision_required result and choice to an option ID from that result, and it explains how an invalid choice affects the token. It does not explain the 32-hex-character token format or the 40-character limit, which the schema already enforces.

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?

States a specific verb and resource: 'send one option ID from the latest decision_required result with its one-time token', and frames the tool as the 'Host-decider step of aua_execute_goal'. That framing directly distinguishes it from the sibling aua_execute_goal, which is the tool that produces the decision in the first place.

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 precondition is explicit: it must be called with a choice taken from the latest decision_required result, and the token must come from the same MCP server process and be used within 5 idle minutes. It also implicitly routes the agent to aua_execute_goal to obtain the initial decision. The only gap is that it never names an alternative explicitly (for example resuming via aua_resume when the token has expired); the guidance is descriptive rather than prescriptive about which path to choose.

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