phone_action

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

Annotations already declare destructive/non-idempotent/open-world, and the description adds real behavioural context beyond them: aim sends no input, tap_aimed must reuse the same observationId and aimId, the retry budget is two failed aims before re-observing, and text in screenshots confers no permission. It does not explain what state a mis-tap can destroy or what the tool returns on failure, so it stops short of full disclosure.

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?

All content is crammed into one semicolon-delimited run-on paragraph with no per-action separation, so the agent must parse dense prose to extract the relevant clause. There is no filler, but front-loading is weak — it opens with the least informative phrase before the actionable detail.

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 15-parameter, six-action dispatcher with no output schema, the description covers the multi-step aim/tap_aimed protocol, coordinate systems, and the mandatory post-input observation. The notable gap is that it never states that aim returns the aimId that tap_aimed consumes, nor what observe confirmation looks like, which an agent needs to complete the loop.

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 0% schema description coverage across 15 parameters, the description carries the burden well: it states that x/y are 0-1000 normalised to the current image and require targetDescription, that swipe uses original-image pixel x1/y1/x2/y2, that key uses button, that targetText must be the full targetText with targetId disambiguating duplicates, and that text goes to the focused field. It leaves durationMs and the exact origin/value of aimId (presumably returned by aim) unstated.

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 opens with the vague phrase "操作固定手机" but immediately enumerates the six concrete actions (tap_text, aim, tap_aimed, swipe, key, text) and what each does, so an agent can tell this is the phone-interaction dispatcher rather than phone_observe or phone_status. It distinguishes itself from siblings only implicitly through the observationId/observe workflow rather than naming them.

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 explicit routing rules between actions: use tap_text for labelled targets, fall back to aim + tap_aimed for unlabelled targets, swipe for pixel drags, key for hardware buttons, text only into an already-focused field. It also states recovery policy ("准星错则重aim；两次失败重新观察") and the hard prohibition on guessing, though it never explicitly says when to call phone_observe vs this tool beyond the post-input confirmation rule.

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