Update Evidence Checklist Item Status

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

Beyond the annotations (all false), the description discloses the key behavioral trait: 'every transition is appended to evidence_status_history with the operator's optional note', which is consistent with idempotentHint=false since repeated calls create additional history entries. It also explains the runtime auto-promotion behavior that owns the 'addressed' status. This enriches context without contradicting the structured hints.

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?

Each of four sentences earns its place moves forward: the role and version, the statuses with crisply scoped definitions, the 'addressed' exclusion, and the history side effect. Context is reasonably|null|. There is no filler or tautology — it reads as a spec, not boilerplate.

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 tool with no output schema, no parameter descriptions, and only negative annotations, the description covers the full decision surface: all four legal statuses, the forbidden status, and the side-effect of appending history entries. Remaining gaps are minor: what response_format returns and the exact provenance of item_id are not explained, but the operator workflow and status semantics are completely usable.

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?

Given 0% schema description coverage, this description carries the semantic weight for the most important parameter, 'status': it defines exactly what each enum value resolves when monitoring an operator action. It also clarifies that 'note' is the optional operator note appended to history. It does not explain session_id, item_id, caller, or response_format, but their schemas' patterns and enums already serve those adequately — the definition focuses its budget where ambiguity is highest.

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 states a specific verb and resource ('Mark a checklist item') and enumerates all four legal statuses with their operational meanings: satisfied, deferred, rejected, open. It clearly signals that 'addressed' is not settable through this tool, which is an additional scope boundary. The operator-workflow framing and status semantics distinguish it from evidence-attachment and judging siblings without needing to name them.

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?

The description gives explicit when-to-use context: each status is mapped to the operator's workflow condition ('operator confirms the ask was answered', 'out of scope for this session', etc.). It also gives a crisp when-not-to-use rule: the 'addressed' status is réservé for runtime auto-promotion and cannot be set here. It does not name alternative sibling tools explicitly, but the exclusion and conditional semantics provide solid routing guidance.

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