Edit property definitions

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

Goes well beyond the annotations: it declares dry-run-by-default, what the preview returns (before/after plus warnings), and precisely what destruction occurs — removing an enum option leaves elements showing <Undefined>, and availability changes have similar consequences, while GUIDs are otherwise preserved. It also names prerequisites (Tapir build with UpdateClassificationItems, Teamwork Properties set reservation), which the destructiveHint annotation 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 highest-value facts: what it edits, that it is dry-run by default, and how to address targets. The example payload is long but earns its place given the untyped `changes` schema. Semicolon-chained clauses make it dense, though not padded.

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 destructive, morphologically complex tool this covers prerequisites, safety default, addressing grammar, and consequence of option removal; an output schema exists so return shape needs no explanation. The only omission an agent could trip on is the undocumented `port` parameter.

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% and `changes` is an untyped array of open objects, so the description carries the load — it supplies addressing conventions ('Group/Name' or GUID, 'System/Code' with '/*', enum options by text or GUID when ambiguous) and a full worked example that effectively defines the object shape. `dry_run` semantics are also explained. The `port` parameter is never mentioned anywhere, which is the one remaining gap.

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 and resource ('Edit custom property DEFINITIONS') and immediately scopes it away from a confusable nearby concept ('not element values'), then enumerates the editable facets (name, description, group, default, availability, enum options). An agent can distinguish it from set_element_data, edit_attributes, and edit_classifications without opening the schema.

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 concrete routing: use search_definitions to resolve 'Group/Name', and reserve_elements with object_sets first in a Teamwork project. It also implies the default is a safe preview ('pass dry_run=false to commit'). It stops short of explicitly contrasting against siblings like import_definitions or edit_attributes, so the when-not guidance is implicit rather than stated.

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