update

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

With no annotations, the description fully carries behavioral disclosure. It warns that notes REPLACES wholesale and discards prior content, explains the composition order of the three write arguments, states that meta_update wins collisions deliberately, and flags reported_at_ref as a sanctioned mutation of an observation-frozen column. This is far beyond a typical update description.

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 description is front-loaded with a clear summary and uses a labeled Args list. It is long, but the complexity of the compose-order and alias rules justifies the length. A few explanatory sentences in meta_update are slightly verbose, but not wasteful.

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?

Despite 0% schema coverage and no annotations, the description covers every parameter, edge cases, collision precedence, destructive behavior, and the special semantics of reported_at_ref. An output schema exists, so return-value details are not needed. The tool is fully callable from this description alone.

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%, but the description documents all 8 parameters, including accepted enum values, case sensitivity, aliases, examples, and semantic behavior (replace vs append vs merge). This fully compensates for the schema's lack of descriptions.

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 opening sentence states a specific action and target: 'Update a finding's status, severity, notes, tags, or metadata.' This clearly identifies the resource (findings) and the exact fields, distinguishing it from generic 'update' and from sibling tools targeting requirements or milestones.

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?

Provides explicit internal routing: notes says to use append_note instead for safe additions, and meta_update is described as the repair path for keys no other argument can reach. It lacks an explicit statement like 'for requirement updates, use reqs_update,' but the finding-focused context makes the intended domain clear.

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