screen_map

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

The readOnlyHint annotation already marks the call as non-mutating, and the description adds genuinely useful behavioral detail a caller could not infer: refs are valid until the next screen_map call, refs_generation identifies the issuing call, and windows are ordered with the topmost first. This materially reduces the risk of stale-ref mistakes.

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?

Each sentence is information-dense and earns its place: the first defines the output, the second gives the decision-relevant purpose, the third explains ref lifecycle and use. It is front-loaded with the core 'coordinates to reach it' idea and contains no fluff.

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?

With no output schema, the description does a good job of explaining return content and ref validity, and the generation marker closes an important ambiguity. However, it stays silent on the limit and widgets parameters, so an agent cannot predict truncation or reduction of the widget list without guessing.

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 only 33%: app is described in the schema, but limit and widgets are bare. The description does not compensate by explaining what limit controls, what widgets=false does, or how app scopes the operation to a non-focused application.

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 names an exact deliverable: screen coordinates for the desktop, windows, pointer, and pressable widgets, and frames the tool as the one that turns 'click the Save button' into a number without looking at an image. This clearly distinguishes it from visual/coordiate tools like screenshot and from ref-consuming tools like ui_press/pointer_click.

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 strongly implies when to use it: any time you need exact pixel/ref coordinates or need to convert a semantic widget into an actionable ref. It even tells the caller what to do with refs, but it does not explicitly name alternatives such as ui_find or screenshot or say when not to use this call.

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