obsbot_tail2_track_target

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

With no annotations, the description carries the full burden and does so well: it discloses the resulting mode is data-dependent ('depends on what is at the point'), that humanTrackingSingleMode is armed autonomously from mode none, and that objectTracking is unreachable because its bounding-box grammar is undecoded. These are non-obvious state-transition facts an agent could not infer from the schema.

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-loads the 'Tap-to-track' concept and the coordinate contract, then layers mode behavior and the readback caveat. It is dense and dash-heavy but each clause adds distinct information; slightly tighter phrasing would help.

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 3-param mutation tool with no annotations and no output schema, the description covers the coordinate contract, mode transitions, verification path, and one hard exclusion. Only the camera parameter's meaning is left unexplained, so it is nearly, but not fully, complete.

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 0%, so the description must compensate, and it does for x/y by defining the normalized 0.01-0.99 range, the top-left ~0,0 origin, and the exact derivation (snapshot pixel / frameWidth|frameHeight). The third parameter, camera, receives no explanation at all, leaving a gap.

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?

States a specific verb and resource ('the camera engages AI tracking on the subject there') anchored to an input coordinate, and it distinguishes the behavior from adjacent paths by naming the modes it can and cannot reach (humanTrackingSingleMode vs objectTracking). An agent can tell this apart from gimbal-aiming or generic track tools from the description alone.

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 clear context: feed a normalized coordinate and tracking engages from mode none, plus an explicit exclusion (objectTracking cannot be entered this way) and a readback instruction via obsbot_tail2_status. It does not, however, route the agent between this and sibling tracking entry points such as obsbot_tail2_ai_track or obsbot_aim_at_pixel, so the alternative-selection guidance is incomplete.

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