flow.run_script

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

The description includes important behavioral flags in brackets: '[approval required][device mutation][risk:dangerous]'. These go beyond the absent annotations and warn the agent about side effects and risk. However, it doesn't disclose what 'approval required' means in practice, what exactly gets mutated on the device, or whether steps run sequentially with rollback. The risk flag is useful but the description could add more context about failure behavior.

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 that front-loads the risk flags and lists the DSL verbs. It is compact and informative, though the long list of DSL operations makes it slightly run-on. No wasted words, but the structure could be improved by separating the risk flags from the functional description.

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 complex tool with 7 parameters, 0% schema coverage, no output schema, and no annotations, the description is insufficient. It explains the DSL concept and lists operations, but an agent cannot correctly construct a call without knowing the format of 'steps', the meaning of 'prefix', 'delayMs', 'testName', 'serverUrl', and 'stopOnFailure', or what the tool returns. The risk flags help, but the operational details are 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 description coverage is 0%, so the description must compensate for 7 parameters. It only explains the 'steps' parameter implicitly by listing DSL operations, and mentions nothing about sessionId, prefix, delayMs, testName, serverUrl, or stopOnFailure. The description adds some meaning for 'steps' but leaves the other 6 parameters entirely unexplained.

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 clearly states a specific verb ('Run') and resource ('a high-level JSON flow DSL over an Appium session') and lists the DSL operations (waitText, tapText, type, assertText, etc.). It distinguishes itself from lower-level Appium tools by being a high-level flow runner, though it doesn't explicitly name a sibling alternative.

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 for orchestrating multi-step Appium interactions via a JSON DSL, and the sibling list shows many granular appium.* tools, suggesting this is the higher-level alternative. However, it doesn't explicitly state when to use this vs. composing individual appium.tap_by_text, appium.type_text, etc., nor does it mention prerequisites like an active session.

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