fit_camera

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

Beyond the annotations it discloses two non-obvious traits: existing cameras are not modified, and the call is rejected unless the current view is saved, with force=true discarding that view. The data-loss warning on force=true is exactly the kind of context annotations cannot express, though it does not state what the response contains or how failure is reported.

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-loaded with the core action, then the safety constraint, then the alternative — a sensible ordering with no filler. It is dense but every clause carries information; only the 'la vue est perdue' parenthetical slightly duplicates the preceding refusal clause.

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?

An output schema exists, so return values need not be described, and the description covers the mutation, its side effects, and the prerequisite for node ids. Minor gaps: no guidance on behavior with an invalid node_id, and the units/semantics of `margin` are left to inference.

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?

With 0% schema description coverage the description carries the burden and mostly does: `name`, `node_id` (valid ids from get_scene_tree detail=true), `margin` (how far to back off), and `force` (only with user consent) are all explained. The exact meaning of `margin` (multiplier vs. absolute distance) and its default of 1.15 remains implicit.

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?

Names a specific verb and resource ('Crée une caméra neuve') and states the exact framing target ('cadrée sur le nœud `node_id`'), the margin behavior, and that the result is saved. It also distinguishes itself from the sibling `set_camera` by noting existing cameras are untouched, so an agent can pick correctly without opening schemas.

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?

Explicitly recommends itself over 'un changement de cadrage manuel', states the preconditions for refusal (current view unsaved), and prescribes when the override applies ('force=true seulement avec l'accord de l'utilisateur'). It also points to `get_scene_tree detail=true` as the source of valid node ids.

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