Kz Sketch

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

With no annotations, the description carries the full burden, and it does disclose a real side effect: it writes a file into the data folder (sketches/<pièce>.svg) and returns the path, plus what the wall/on_top/ceiling lists and the schedule nomenclature contain. It says nothing about permissions, error behavior for an unknown room, or whether an existing sketch is overwritten, which are the remaining behavioral gaps.

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 purpose is front-loaded in the first clause, followed by rendering details and the file/return behavior. The semicolon-chained second half packs a lot into one run-on paragraph, but each clause (file location, return value, list meanings, schedule contents) carries real information.

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 generator tool with an output schema and two optional parameters, the description is nearly self-sufficient: it covers scope, rendered elements, the side effect on disk, the return path and the meaning of the output lists. Given the output schema exists, the extra explanation of return contents is a bonus rather than a requirement.

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 coverage is 0%, so the description must compensate, and it largely does: room is explained as the target piece defaulting to the main building when absent, and decor_path is tied to DECOR.md and to a visible rendering effect (wall paint outlined in palette colors). Only the expected format of room (name vs. identifier) is left unstated.

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 concrete verb and resource ('Plan SVG vu de dessus d'une pièce'), enumerates the rendered content (murs, portes, fenêtres, tapis, meubles, luminaires) and states the default scope when room is absent. It clearly identifies what the tool produces, though it never contrasts itself with siblings like kz_board or kz_summary.

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?

There is no explicit statement of when to choose this tool over the alternatives in the catalog (kz_board, kz_summary, kz_room_geometry, kz_check_room). The phrase 'si room est absent' only explains a parameter default, not usage context, and no exclusions or prerequisites are given.

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