modx_update_element_property

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

With no annotations, the description carries the full burden and does well: it discloses that other property definitions and source code are preserved, that the underlying mechanism is the standard MODX update processor, and that a compare-and-swap is enforced through expected_value. It stops short of saying what happens when expected_value mismatches (error vs. silent no-op) or how the element is located.

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 tight sentences, front-loaded with the core action and restrictions, with the CAS and preservation guarantees packed into the second. Dense but every clause carries information; a slight readability cost from cramming four guarantees into one semicolon-separated sentence.

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 mutation tool with no annotations, no output schema, and 7 parameters at 14% schema coverage, the description covers the mutation semantics well but leaves the identification contract (id vs. name) and the failure mode of the compare-and-swap unexplained. Those are the gaps most likely to cause a mis-call.

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 only 14% across 7 parameters, so the description must compensate, and it only clarifies expected_value and property_name semantics. The critical ambiguity of id vs. name is untouched—neither is required in the schema, so the agent has no guidance on which identifier to supply or whether both are allowed—and value and _runtime_preconditions are undocumented.

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 a specific verb and resource ('Change ONLY the value of one EXISTING default property') and enumerates the supported element types (snippet, chunk, plugin, template), so the scope is unambiguous. It implicitly distinguishes itself from broader element editing by the capitalized 'ONLY' and 'EXISTING', though it never names a sibling such as modx_update_element or modx_edit_element_lines.

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?

Usage is implied rather than stated: the CAS requirement via expected_value and the 'EXISTING default property' restriction tell the agent this is for narrow, safe single-property edits, not creation or whole-element edits. However, no alternative tool is named for creating a new property or editing source code, so the agent must infer routing from sibling names alone.

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