create_cabinet

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing beyond units: not whether the call persists state, what a "revision" implies about versioning or duplication, whether permissions are required, or whether defaults apply to omitted spec fields. For a mutation tool with destructiveHint unset and no readOnlyHint, this is a significant gap.

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?

Two short sentences, front-loaded with the operation and followed by the unit convention, with no filler. The brevity is appropriate, though the ambiguous term "revision" consumes part of a very small budget that would have been better spent on the spec fields.

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, but the tool is a nested-object creation call with 0% schema description coverage and zero annotations. Given that complexity, the definition should say what a revision is relative to an existing design and roughly what panel_mm, back_mm, and shelves control; none of that is present.

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% across a nested spec with seven sub-properties (back_mm, shelves, depth_mm, material, panel_mm, width_mm, height_mm), so the description needs to compensate. It does add real meaning by stating that all dimensions are in mm and mapping axes as X=width, Y=depth, Z=height, which the schema does not say. However, back_mm, panel_mm, shelves, and material remain undefined beyond their names and ranges.

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 verb and resource: "Create a cabinet revision." That distinguishes it from update_cabinet at a basic level (create vs. update), but the word "revision" is never explained, so it is unclear whether this creates a new cabinet, a version of an existing one, or both. An agent can identify the operation but not the precise object being created.

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 guidance on when to use this instead of update_cabinet, no prerequisites, and no indication of whether an existing cabinet must exist first or whether the revision needs to reference a parent design. The only usage-adjacent content is the unit convention, which is not a when-to-use rule.

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