Run the annotation agent

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 it does so thoroughly. It discloses the five-phase execution flow, the single-active-run constraint, the 409 conflict with active_run_id, the attach_if_active escape hatch, bounded server-side LLM costs, the 202 response containing run_id, and the recommended follow-up call.

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?

Three dense sentences deliver the action, constraints, status code, cost behavior, and next step without filler. Key information is front-loaded: the operation and phases come first, followed by edge-case handling and follow-up.

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?

Despite lacking annotations and an output schema, the description is complete enough to invoke the tool correctly: it states what the run does, how to handle an existing active run, what response shape to expect (202 and run_id), cost implications, and the next monitoring call.

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 adds meaning for attach_if_active through the active-run constraint and for the run_id response. However, it never explicitly defines scan_id beyond the word 'scene' appearing in context, leaving the required parameter under-explained.

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 opens with a specific verb ('Start') and a precise resource ('five-phase scene annotation run'), listing the phases. It clearly distinguishes itself from siblings like agent_chat, agent_pilot, or scene_measure_distance by framing this as a structured annotation workflow on the server-side scene agent.

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 gives clear operational context: a run should be started, there is one active run per scene, and the caller should follow with agent_run_events wait_for_done. It also explains the attach_if_active option. However, it does not explicitly state when not to use this tool or name alternatives, so it stops short of a 5.

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