update_usem_rule

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

Goes well beyond the annotations: every field is read back after the write, unpersisted values fail with FIELDS_NOT_SAVED, assignment_group_fields triggers a run-once server script with a wait_seconds bound, and the operation is flagged as an admin-level config change needing WRITE_ENABLED. All of this is consistent with readOnlyHint=false and idempotentHint=true.

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?

Dense but every sentence carries information: scope, verification behavior, error code, the scripting side effect, and the write gate. The write-gate warning sits at the end in brackets rather than being front-loaded, which slightly weakens scanability.

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 4-parameter write tool with no output schema and a nested free-form fields object, this covers verification, failure mode, side effects, and prerequisites. Remaining gaps are behavioral detail (partial update semantics, what happens on rule_type/field mismatch), which are minor.

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 100%, so the baseline is 3, but the description adds real value: the fields object is the union of all USEM rule columns and is further restricted at runtime by the selected rule_type. It doesn't clarify replace-vs-merge semantics for partial fields objects, keeping it from a 5.

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 (Update) and resource (USEM/VR automation rule) plus the keying mechanism (by sys_id) and payload shape (fields object restricted to a per-table allowlist). It is clearly distinguishable from siblings like create_usem_rule, get_usem_rule, set_usem_rule_active, and the other update_* tools.

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 clear context on prerequisites (WRITE_ENABLED=true, SCRIPTING_ENABLED=true for script-written fields) and on which fields the runtime accepts. It doesn't explicitly name alternatives (e.g., use set_usem_rule_active to toggle active, create_usem_rule for new rules), so routing guidance is implied rather than stated.

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