ptz_goto_preset

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly conveys that the tool performs a physical move action and adds useful behavioral context such as the host format and that camera_id is required and sourced from list_cameras. It does not mention side effects like whether the preset must exist or the camera must be online, but the core mutating action is evident.

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 compact and well-structured: one purpose sentence followed by a concise parameter breakdown. Every line earns its place, and the required camera_id is highlighted prominently.

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?

Given the simple three-parameter tool and the presence of an output schema, the description is fairly complete. It covers all parameter semantics and even tells the agent where to obtain camera_id. Minor gaps include not stating that the preset must exist or the camera must be online, but these are reasonable assumptions for a PTZ move action.

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. It fully does: host is explained as console name, ID, or composite ID (MAC:numericId format), slot is described as the preset slot number, and camera_id is marked as REQUIRED with a pointer to list_cameras. This provides essential meaning beyond the raw schema types.

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 starts with a specific verb and resource: 'Move a PTZ camera to a preset position slot.' This clearly states what the tool does and is easily distinguishable from sibling PTZ tools like ptz_patrol_start and ptz_patrol_stop.

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 provides clear parameter context (host format, slot meaning, camera_id source) but does not explicitly say when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites beyond obtaining camera_id. The usage is implied from the purpose but not directly stated.

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