Edit Hatch

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

The description goes beyond the sparse annotation (destructiveHint=false) by revealing the partial-edit contract: omitted parameters are left untouched, so the tool will not reset unspecified values. It also explains the `changed` result semantics, including the empty-list behavior for no-op updates.

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?

Three short sentences with no filler. The key action is front-loaded, and the behavioral caveats are stated compactly without repeating schema details.

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?

Given the output schema covers return shape and the annotations cover the non-destructive hint, the description adds exactly the missing operational context: partial edits are safe, and changed results distinguish real changes from no-ops. The single required parameter and optional fields are sufficiently documented in the schema.

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 valuable cross-parameter semantics: omitted parameters are left alone, tying the null/empty defaults to a 'no change' meaning across all optional fields, which is not obvious from the individual schema descriptions alone.

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?

States a specific verb ('Edit') and a specific resource ('an existing hatch') with the modifier 'in place,' which clearly distinguishes it from creation tools like entity_create_hatch or hatch_add_boundary. The scope is immediately understandable.

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 phrase 'existing hatch' gives clear context: use this when modifying an already-created hatch, not when creating one or adding geometry. It does not explicitly name alternatives or exclusions, but the implied usage boundary is strong.

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