personal_capture_user_turn

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

With no annotations present, the description carries the behavioral disclosure burden. It discloses that writes are conditional on a passing preflight and that the tool rejects writes otherwise, plus the post-capture requirement to derive and finalize. It does not cover return values or idempotency, but for a narrow capture tool the key behaviors are stated.

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 two short sentences with no filler. The core purpose is front-loaded, and every clause adds either a precondition, a behavior, or a follow-up requirement.

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 six parameters, no output schema, and no annotations, the description provides the essential workflow guards but leaves parameter semantics and return/error behavior to inference. It is sufficient for an agent familiar with the domain, but not fully self-contained for a generic caller.

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, but it only loosely alludes to 'complete user message' (text) and 'turn receipt' (turn_id/capture_id). The optional parameters captured_at, message_kind, and conversation_id are entirely unexplained, leaving the agent to infer their meaning from names alone.

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: bind a pre-assessed personal turn receipt and save the full user message verbatim. It also clearly distinguishes the tool's role by referencing the preflight prerequisite and the required derive/finalize follow-up, placing it in an unambiguous pipeline.

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 gives explicit when-not-to-use conditions: if there is no preflight or preflight marks the turn non-personal, writes are refused. It also states that after capture, derivation and finalization are mandatory, effectively instructing the agent on the required next steps within the sibling toolset.

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