track_start

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 richly: it discloses the closed-loop iteration, that it decides only from the picture because the camera's position report is untrusted, that it emits a residual offset each iteration, that a losing loop is visible rather than silent, and that it continuously observes the room and any people in it. Termination conditions (subject lost, dead-zone settle, max_seconds) and the 25-degree-per-iteration cap are also spelled out.

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 in the first sentence and the subsequent paragraphs each cover a distinct concern: loop behavior, privacy/observation scope, termination, and parameter tuning. Some phrasing is decorative ('closing the loop on the picture', 'looks like one instead of seeming to work'), which costs a little density but does not bury the actionable content.

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 5-parameter mutation-style tool with no annotations and no output schema, the definition covers the behavior, consent/privacy implication, stopping conditions, and the two tuning knobs that most often go wrong. The gap is the undocumented target parameter and the units/meaning of dead_zone_px, which an agent would have to guess.

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%, so the description must compensate, and it does well for gain ('degrees of camera movement per pixel of offset', a starting point not a measurement) and invert (direction flip for differently mounted cameras, with a diagnostic for detecting a wrong sign). It partially covers max_seconds and dead_zone (settle condition), but says nothing about target or its accepted values, leaving one parameter undocumented.

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 opening 'Start following a subject, closing the loop on the picture' gives a specific verb (start) and resource (a subject-tracking loop), which clearly separates it from track_stop and track_status. The follow-up paragraph confirms it is an iterative detect-measure-step loop rather than a one-shot move like aim or nudge.

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 states directly when to use it ('Start it when the user wants the camera following something') and when to stop ('and stop it when they do not'), plus the self-termination cases. It also routes the agent to read track_status and restart with invert when the direction is wrong, though it never contrasts outright with other movement siblings such as aim or recentre.

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