aua_execute_goal

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), it discloses what data leaves the device (visible app UI text sent to TypeSafe in Jev mode, nothing sent in host mode), what happens after mutations (effect_timeout_seconds bounds observation; unresolved effects hand off without another mutation), and warns that status=handoff is not success and geometry-only changes do not prove an effect. That is unusually rich disclosure about side effects, data egress, and result interpretation.

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 first sentence is well front-loaded and the description is dense with useful substance rather than filler, but it reads as a run-on paragraph of terse fragments ('Compact semantic state and parallel operation/target questions share one Jev request per step') with no grouping by concern. Several sentences require re-reading to parse, which hurts scanability for a long definition.

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 16-parameter, non-idempotent, open-world tool with no output schema, the description does cover return statuses (decision_required, handoff, stop_reason=model_goal_achieved with an 'unverified: check it' caveat) and safety behavior well. However, the majority of tuning parameters are unexplained, and the one-time token workflow is described only in passing, so an agent still lacks enough information to set non-default parameters confidently.

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% across 16 parameters, so the description carries the full burden. It does explain goal, package, texts, completion/completion selector, decider, input_macros, max_steps ('counts candidate selections, with at most two native writes per input macro'), and effect_timeout_seconds, but leaves actions, observe, variation, min_margin, min_probability, max_model_calls, timeout_seconds, and completion_state entirely undocumented.

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 opening sentence states the mechanism clearly: an agent plans, a decision policy selects candidate IDs, and Android Use executes them, so the tool reads as a bounded goal-execution orchestrator rather than a primitive action. It also signals the boundary with primitive siblings via 'Keep existing tools for planning, unsupported controls and recovery,' though it never names a specific sibling tool.

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 concrete routing conditions: decider=auto prefers Jev when enabled, falls back to host, and host mode returns status=decision_required that must be resolved with aua_goal_decide. It also states exclusions (password screens hand off, keep existing tools for planning/unsupported controls), but does not say when to prefer this over aua_screen_action or aua_batch for a given task.

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