cao_visite_plan

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

With zero annotations, the description carries the full burden and succeeds: it discloses the HTTP 400 construction_critique refusal, the API-key requirement, the single-engine (browser GPU) rendering model, the auto room-detection algorithm (walls → flood fill → room centres → doorways), and the verbatim-and-checked behavior of an edited `chemin`. This is a thorough behavioral profile for a planning endpoint.

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 long but dense; for a 17-parameter tool with no annotations, nearly every sentence earns its place. The critical cao_verifier warning is front-loaded ahead of the main purpose, followed by output shape, rendering workflow, and adjustment. It is slightly over-packed — the lens-catalogue and REST endpoint details could arguably be moved to a separate field — but it avoids fluff.

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?

With no output schema, the description correctly explains the return structure ({plan:{objectif, cadence, plans[], chemin[]}, alertes[], resume}) and the consumption workflow (paste into the editor or call window.CAD_startCinematicTour). Minor gaps remain — the distinction between `plans[]` and `chemin[]` in the output is not explained, and `alertes[]` content is unspecified — but for a tool this complex, the definition is unusually 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 description coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: the CAO coordinate system (x=right, y=depth, z=height), the waypoint-level interpretation of `chemin` (position/vise), and the resend-with-edited-`chemin` adjustment loop for `objectif`/`cadence`. It does not document every parameter's cross-effects, but the schema already covers parameter-level detail.

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 states a specific action — 'DIRECT the 4K cinematic visit of a CAO scene: choose the LENS ... and the CAMERA PATH' — with a clear use-case framing ('SEEN in motion rather than read on a flat plan'). It is clear and specific, but it does not explicitly distinguish itself from the closely named sibling cao_visite_camera, so perfect disambiguation would require checking that sibling's definition.

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 opening 'WHEN...' clause states the use condition, and the 'IMPORTANT: call cao_verifier FIRST and fix every severite=critique' instruction gives an explicit prerequisite plus the exact failure mode it prevents (HTTP 400 construction_critique). It does not name when-not-to-use alternatives (e.g., static render via cao_rendu or flat plan via cao_pdf), so exclusions are only implicit.

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