tandem_desktop

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

With zero annotations the description carries the full burden and does so well: it discloses the authorization gate, that repeated or lost claims never authorize replay, that cancel only retires queued work before execution, that cancelled is an administrative record rather than a GUI result, and that host tool timeouts still apply and the session must stay open. The one flaw is that the 'execute=true' authorization is never a documented parameter anywhere in the schema, so the central safety mechanism is uninvokable as described.

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?

Purpose is front-loaded correctly, but the remainder is a single dense paragraph interleaving seven different action contracts (submit, next, finish, cancel, get, status, list) with no segmentation, bullets, or action labels. Every sentence is substantive, yet the lack of structure forces the agent to re-parse to find the rules for one action.

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 seven-action, 18-parameter nested tool with no annotations, the lifecycle coverage (submit -> next -> finish, plus cancel/get) is substantial, and the output schema carries return shape. Gaps remain: the 'list' action is never described, 'status' is only implied, and the phantom 'execute' parameter leaves the authorization path under-specified for a tool gating GUI control.

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 18 nested properties, so the prose does real work: it explains request_id stability, worker_id/claim_id on 'next', claim_token on finish, job_id plus nonblank reason on cancel, the passed/failed/blocked report shape, and wait_seconds semantics. But app vs apps, expected, scenario, build, limit, and launch_instructions go unexplained, and it references an 'execute' flag that does not exist in the schema — actively misleading for a caller building a request.

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 — 'Hand off live UI tests to an already authorized desktop client' — and adds a negative scope statement ('neither launches a model nor grants GUI access') that separates it from model-launching siblings like tandem_start. It does not, however, distinguish this tool from siblings that also offer cancel/list/wait semantics (tandem_cancel, tandem_list, tandem_wait), so an agent must guess which surface is canonical.

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 concrete usage context: the operator owns the external desktop-qa queue, the bound project sets scope, wait_seconds=null blocks vs 0 peeks, and execute=true is required to authorize a claim. What is missing is explicit routing — nothing says when to prefer this tool over the sibling cancel/list/wait tools whose names collide with this tool's actions.

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