point_out

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: marks turn green and disappear when the user acts, wait=true blocks until DONE/GONE/LEFT/NOT DONE with those exact return states, marks follow scrolling elements and vanish on app changes or other phone actions, and a no-marks call removes them. This is unusually rich behavioral disclosure for an unannotated tool.

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 front-loaded with the core action and mechanism, then layers in behavior. It is long but dense, with each clause carrying real information (return states, lifetime, scrolling behavior). It is somewhat run-on and could be broken into shorter sentences for readability, but no sentence is filler.

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 tool with no annotations, no output schema, and four parameters, the description supplies what an agent needs: what it draws, how it behaves over time, what wait returns, how marks are removed, and when they disappear. Nothing essential to calling it correctly appears 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 coverage is 75%, so the schema already documents most parameters; the description adds meaningful semantics for wait=true (blocking until DONE or GONE/LEFT/NOT DONE) that go beyond the schema's brief text. It also clarifies the removal semantics of an empty marks call, though it adds little extra detail for x/y/element beyond the schema descriptions.

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 gives a specific verb ('Show the user where to look or what to do') and a concrete mechanism ('a box, circle or arrow with a short label around up to 6 elements, drawn over the app without blocking their touches'). It clearly distinguishes itself from action tools like tap by framing the marks as guidance 'instead of doing it for 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?

It explicitly states the intended use case ('guide the user step by step through something they want to learn to do themselves, one step per call, instead of doing it for them') and even covers the removal case ('Call with no marks to remove them'). It does not name a specific sibling tool like tap or notify as the alternative, but it does describe the contrasting behavior.

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