set_reference_field

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

No annotations are provided, so the description carries the full burden, and it does so well: it discloses the commit-confirmation model ('confirmed by the resolved presentation reading back'), the return shape, and the hard length-fixing constraint on the edit buffer. It omits auth/permission prerequisites and rate/state preconditions, keeping it short of a 5.

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?

The action is front-loaded, but the paragraph is dense with backticked wire bytes and repeated mechanism detail, making it harder to parse than necessary. Every sentence carries information, yet the same constraint is effectively restated, so it is not optimally tight.

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 unusual replay-based complexity and the existing output schema (which covers the {field, value, committed} return), the description supplies the constraints an agent needs to call it correctly. It is complete for the core operation, missing only permission/state prerequisites.

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 0%, so the description must compensate, and it largely does: it defines value as a catalog element NAME, explains captured_value as the length-defining reference, and frames capture as the source session. host/port remain undocumented but are self-evident network defaults.

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 uses a specific verb+resource ('Set a CatalogRef field') and explains the native reference-input mechanism, which distinguishes it from the sibling string-write tools it explicitly contrasts itself against ('same fixed-width limit as the string write'). The core action is unambiguous, though the surrounding wire-format detail obscures rather than sharpens the one-line purpose.

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?

It states the operative constraint (value must match captured_value's character length, and re-capture for other lengths), which is useful usage guidance. However, it never states when to prefer this over siblings like set_choice or write_form_value, so alternative-selection guidance is only implied.

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