Generate test assets from recorded actions

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, non-idempotent, closed-world), and the description adds real context beyond that: default save behavior differs by target, plan is a read-only preview, fresh_state requires stateProfile, integrateIntoProject is consent-gated and never overwrites, and compile defaults on. It does not disclose where files land, what happens on repeat runs, or any cost/latency traits of bootstrap, which matters for a 23-param generator.

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?

Front-loaded with the core action and immediately followed by the target taxonomy, which is the highest-value information. The telegraphic style ("mode:"plan" previews", "appium: record actions first when none exist") packs a lot in, though the fragment-heavy phrasing and unglossed target names like "pom" and "TC catalog" cost some readability.

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 23-parameter, five-mode generator the description covers the important behavioral edges (preview vs write, consent gating, non-overwriting integration) but leaves notable gaps: it never states that sessionId is required for every target except appium, nor explains approve, budgetProfile, includeCi, or device. There is no output schema to fall back on, so those absences are real.

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?

With 91% schema coverage the baseline is 3, and the description earns above that by exposing cross-parameter dependencies the schema lists only locally: replay:"fresh_state" needs stateProfile, consentId applies to suite fresh_state and appium project writes, save defaults are targets-specific, format defaults to both, and brittleThreshold/candidateOnly semantics for appium validation. Several parameters (name, approve, budgetProfile, feature, includeCi, device) get no description-level meaning, keeping it below a 5.

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?

Opens with a specific verb and resource ("Generate reusable test assets from the actions recorded in this session") and then enumerates every target value (flow, pom, suite, testcases, appium) with parenthetical detail on what each produces. It also explicitly names the sibling to use for the durable repo case ("Durable repo suite: qa_suite_generate"), so an agent can route between them without opening a 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?

Gives per-target selection guidance (suite is "replay-gated", appium "can bootstrap from projectRoot", flow emits Flow V2 YAML) and states that mode:"plan" previews rather than writes. The one exclusion it draws is against qa_suite_generate. It stops short of saying when target X should be chosen over target Y for a given intent, so selection among the five targets still needs inference.

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