Kz Board

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

With no annotations at all, the description carries the full behavioral burden. It does disclose the important trait: this is a derived-artifact writer that consumes DECOR.md and emits files relative to it ('écrit à côté du DECOR.md'), which implies a filesystem mutation. It omits overwrite semantics (does re-running replace PLANCHES.md and clear plans/swatches?), prerequisites (must DECOR.md exist), and failure behavior — significant gaps for a mutation tool.

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 output artifact is front-loaded in the opening phrase and every clause carries information — the nested parenthetical enumerates the document contents rather than padding. It is a single very long sentence with heavy nesting, which costs some readability but adds no filler.

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 explained, and the description covers what is generated, where it lands, and when to re-run. For a one-parameter generator this is close to sufficient; the missing piece is mutation semantics (overwrite/idempotency) and the precondition that DECOR.md already exists.

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% for the single decor_path parameter, so the schema supplies no meaning. The description partially compensates by making clear that it reads the DECOR.md file per room and writes outputs adjacent to it, which tells the agent the path also determines output location. It never states the expected format of decor_path (directory vs. file path) or what happens if it points at a missing or malformed file.

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 names the action (writes a deliverable) and the concrete artifacts produced: PLANCHES.md plus the plans/ and swatches/ folders, with an enumerated internal structure (overview, swatch sheet, room table, dimensioned plan, sections, finishes, BOM). That is far beyond restating the name 'kz_board', so an agent can tell what it produces. It stops short of a 5 because the artifact-level purpose is buried in a dense parenthetical and the relation to sibling generators is only implied.

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?

'À relancer après chaque kz_save' gives an explicit trigger condition tied to a named sibling, so the agent knows when to invoke it. It does not state when NOT to run it (for example, whether it is wasteful to re-run with no changes, or whether it requires kz_save to have happened first), so no alternative routing is provided.

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