Move or reshape a boundary, keeping its name and properties

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

Annotations already declare destructive=true, idempotent=true and openWorld=true, but the description adds value beyond them: it enumerates the preserved invariants (id, name, properties, set) and the consequence for lookups, discloses the points-per-boundary cap refusal and that refusals are unbilled, and scopes mutation to 'only boundaries on this account'. That is substantial behavioral context the annotations cannot convey.

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 preservation semantics, then the anti-pattern, then resolution and validation behavior. Every sentence carries information, but the five-paragraph block is longer than strictly necessary and could be tightened without losing substance.

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?

With no output schema, the description compensates by describing the ambiguous-name response (a list of ids and a prompt for one) and the refusal behavior for cap violations. Combined with the schema's full parameter coverage, an agent has everything needed to invoke and interpret this tool.

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, but the description goes further by explaining the id/name resolution mechanism ('Name the boundary by set and name; this finds its id') and the disambiguation path when two boundaries share a name (ids listed, one requested). That adds real semantics over the schema, though it does not describe geometry coordinate constraints beyond what the schema already documents.

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 ('Replace the shape of') and a precisely scoped resource ('ONE existing boundary'), and immediately distinguishes the operation from its sibling add_boundary by contrasting with 'delete it and add it again'. An agent knows exactly what changes (geometry) and what does not (id, name, properties, set).

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?

Gives an explicit positive case ('Use this to fix or move a zone') and an explicit anti-pattern ('Do NOT delete it and add it again') with the reason (new id, lost properties). This is a when/when-not/alternative triplet, which is the top of the scale.

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