handover.tools

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

With no annotations, the description carries the full burden and does so well: it discloses idempotency ('calling again with the same seq changes nothing'), monotonic cursor behavior ('never moves back or past the last stored message'), the read-receipt semantics the peer observes, and a side effect ('slides the channel's expiry'). This is exactly the behavioral context missing from structured fields.

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?

Every sentence earns its place and is dense with behavioral facts, with no filler. The lead sentence front-loads the client instruction rather than the tool's core effect, which slightly buries the most important framing.

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?

With no annotations and no output schema, the description still covers the invocation trigger, idempotency, cursor invariants, side effects, and the peer-visible consequence. Nothing an agent needs to call this correctly is missing.

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 two parameters are already documented, establishing a baseline of 3. The description adds genuine semantics for seq by explaining what 'processed' means behaviorally (monotonic, idempotent, tied to the read receipt), though it adds little for key beyond the schema.

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 never states the verb 'acknowledge' directly, but it clearly conveys the purpose: advancing the read cursor so the peer sees messages as read. It distinguishes itself from channel_fetch by tying invocation to a prior peek fetch. An agent can identify what it does, though the framing is indirect rather than a crisp verb+resource statement.

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 explicitly says to use the local client rather than calling by hand, and pins the trigger condition: 'After a fetch with peek=true, the client calls this with the highest sequence number it processed.' Both the when-to-call and the preferred alternative are stated outright.

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

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

With no annotations, the description carries the full burden and discloses the key behavioral traits: immediate deletion of the channel, both keys, and all stored messages, plus the effect on the other side's next fetch. It does not mention authentication requirements or irreversibility explicitly, but the destructive and cross-party consequences are well covered.

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?

Two short, front-loaded sentences with no wasted words. The most important consequence (deletion) is stated immediately.

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 single-parameter, annotation-free tool with no output schema, the description covers what the tool does, who can trigger it, what is destroyed, and how the other side is affected. Nothing essential for correct invocation is missing.

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?

The schema has 100% description coverage for the single 'key' parameter, so the baseline is 3. The description adds only the context that either side can close, without further detail on the key's format or source.

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 ('close') and resource ('channel'), and adds the destructive consequence ('deletes the channel, both keys, and every stored message'). This clearly distinguishes it from siblings like channel_open, channel_join, channel_fetch, and channel_send.

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 notes that 'Either side can close,' which is a useful usage constraint, but it does not say when to close versus alternatives or when not to close. Usage is implied rather than explicitly guided.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the marking semantics with and without peek, the side effect that messages are kept for older clients, the re-fetch behavior of after=N, paging via more=true, and the SPAKE2 pairing side effect on side A.

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?

It is front-loaded with the most important directive (use the client, not a manual call), but the body is a dense single paragraph of stacked parentheticals that is hard to parse. The content mostly earns its place given the tool's complexity, but the structure could be cleaner.

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 complex, annotation-free tool with no output schema, the description covers return nature (ciphertext), paging, acknowledgment workflow, and the pairing side effect. It is close to complete, with only error/edge-case behavior unaddressed.

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 goes beyond the field docs by explaining the default of after (what this side has already fetched), the retry semantics of passing a smaller vs. last-processed N, and the contrast between peek=true and the default marking behavior.

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: 'Returns the peer's messages this side has not fetched yet,' which is clear and actionable. It also names channel_ack as the downstream sibling, though it does not explicitly contrast itself with channel_send, so sibling differentiation is present but partial.

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?

Explicit when-to-use ('Call only when the person asks'), a stated preferred path (use the local client rather than calling by hand), and a full workflow with alternatives: fetch with peek=true, then channel_ack, and how after=N interacts with reprocessing. This is exactly the when/when-not/alternative guidance expected.

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

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

With no annotations, the description carries the full burden and does so well: nameplate is consumed on success, unknown/used/expired nameplates are deliberately indistinguishable (error behavior), the return payload is named (this side's key plus peer SPAKE2 message), and a hard security constraint is stated (the 5-char password must never reach the server).

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?

Three tight sentences, front-loaded with the tool's role in the pairing flow, followed by argument rules, lifecycle, and error semantics — no filler. Slightly dense, but every clause carries operational information.

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?

No output schema exists, yet the description names the return values, the consumption side effect, and the indistinguishability of failure modes. For a security-sensitive pairing tool, nothing an agent needs to invoke it correctly is missing.

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 schema already documents both parameters and the 3-character nameplate format. The description goes beyond it by explaining why only 3 characters are sent and that the remaining code is a password that must stay client-side, adding real meaning to the nameplate argument.

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 and resource (join the channel as the second half of pairing) and identifies the execution context (local client at channel.py). An agent can distinguish this from channel_open, which must be the first half of the pairing flow.

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 'second half of pairing' framing and the client-script reference make the when-to-use context clear, and the code-splitting rule (3 chars here, 5 chars never sent) is an actionable precondition. It stops short of explicitly naming channel_open as the required predecessor by tool name or stating when-not to call it.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses that only a 3-character nameplate is returned, that the server never sees the password (SPAKE2), and that the call counts as one write against the daily quota. It does not say how long the channel remains open, what happens if join never occurs, or whether it is reversible before pairing completes — minor gaps for a stateful write. No annotation contradiction exists since none are provided.

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?

Purpose is front-loaded, and each sentence carries distinct operational value (client requirement, nameplate/password handoff, security model, human gating, quota cost). It runs six sentences, which is on the long side, but almost none is filler.

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?

There is no output schema yet the description explains the return value (3-character nameplate) and the follow-up handoff, so an agent knows what to do with the result and where it goes. Combined with the quota and SPAKE2 notes, nothing essential for correct invocation is missing.

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 100%, so pake_msg is already documented as a Base64 SPAKE2 message from the local client (side A). The description largely repeats that origin information rather than adding format, size, or encoding detail beyond the schema, so the baseline 3 applies.

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 opens with a specific verb and resource — pairing two agents on different machines for a multi-round exchange — and immediately situates it as the starting side of a two-machine handshake. An agent can distinguish this from channel_join without opening the schema, since the side-A flow (generate secret, receive nameplate) is described.

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 explicitly to use the local client and 'do not call this by hand,' and it defines the human-in-the-loop rule (send only after approval, fetch only when asked). This is an unambiguous when/how-to-invoke directive that no sibling tool would contradict.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses the input provenance constraint, the rejection condition for plainspeak base64, the human-approval prerequisite that the server cannot enforce, and the return payload (sequence number and peer read position). This is substantially more than the schema conveys.

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?

Three sentences, each carrying a distinct load: purpose, provenance/precondition, and return shape. The action is front-loaded and there is no filler.

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 two-parameter mutation-style tool with no annotations and no output schema, the description covers prerequisites, prohibited usage, rejection behavior, and return values. Nothing an agent needs to invoke this correctly is missing.

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 meaning for the ciphertext parameter: its provenance (local client), the prohibition on encoding plaintext, and the server-side rejection behavior. It adds nothing about the 'key' parameter, which the schema already documents.

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 first sentence states a precise verb and resource: relaying one ciphertext to the other side of a paired channel. That is clearly distinct from the sibling operations (channel_fetch, channel_open, channel_join, channel_close), and an agent can tell it apart without opening any schema.

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-and-when-not guidance: the ciphertext must originate from the named local client, it must not be called by hand, plaintext must never be base64-encoded into it, and it may only be sent after a human approves the draft. The alternative (calling it manually or fabricating ciphertext) is explicitly ruled out.

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

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

With no annotations, the description carries the full burden and does so: it discloses single-use semantics ('can be fetched only once'), code normalization, the deliberate indistinguishability of unknown/already-fetched/expired failures (a security property), and the verbatim-and-complete return obligation. This is behavioral context an agent could not infer from the schema.

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?

Front-loads the core action and the code format, then layers failure modes and the channel-link exception. Every sentence carries distinct operational content; none is filler or restatement of the title.

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?

There is no output schema, and the description compensates by specifying the return contract: content on success, null plus a reason on failure, and the specific channel_code reason. Nothing an agent needs to call or interpret the result is missing.

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 code parameter is already documented, but the description adds real meaning beyond it: case-insensitivity, hyphen stripping, the worked example pair, and the fact that a full handover.tools URL is acceptable input. It stops short of describing any other accepted input forms.

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 and resource ('Fetch content stored by handoff_put') and ties it directly to the sibling that produces the input. An agent can immediately distinguish it from handoff_put, handoff_revoke, and the channel_* 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?

Explicitly names the producer (handoff_put) as the precondition, and states the negative case: a channel link must be joined with the channel client, not fetched here. It also tells the agent what happens if the wrong kind of code is passed (reason channel_code with steps).

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

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

With no annotations, the description carries the full burden and does so exceptionally: it discloses that content is NOT ENCRYPTED and server-readable, the TTL and default burn-after-read deletion semantics, the returned revoke_key and how to use it, and asymmetric rate limits (writes capped daily, reads uncapped). This is exactly the behavioral profile an agent needs before writing potentially sensitive text.

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?

Front-loads the core action in sentence one, then layers the safety warning, lifecycle behavior, and rate limits in a compact flow. Despite its length, every sentence conveys a distinct operational fact with no filler.

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?

With no output schema and no annotations, the description still communicates the return values (short code, revoke_key), the security posture, lifecycle/destruction behavior, and rate limits. Nothing an agent needs to call this correctly is missing.

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 100%, so the schema already documents label, content, ttl_minutes, and burn_after_read. The description reinforces the defaults and the once-only behavior but adds no syntax or format detail beyond what the schema provides, which is the expected baseline when the schema does the heavy lifting.

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+resource pair (store context, get back a short code) and the cross-device handoff scenario, which cleanly separates it from handoff_get (fetch) and handoff_revoke (destroy). An agent immediately knows this is the write side of a transfer flow.

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?

Explains the use case clearly ('give the link to an agent on another device... no copy-paste of long text') and names handoff_revoke for the reversal case. It does not, however, say when to prefer this over the sibling channel_send for moving content, which is the main remaining ambiguity.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that destruction is immediate and overrides TTL, that it works whether or not content was fetched, that authorization requires the writer's revoke_key, and that an already-gone item returns 'already_gone' rather than failing. This is exactly the behavioral context an agent needs before invoking a destructive operation.

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?

Four short sentences, each doing distinct work: what it does, the authority constraint, when to reach for it, and the idempotent-outcome note. The destructive action and its immediacy are front-loaded.

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 single-parameter destructive tool with no annotations and no output schema, the description covers everything material: scope, timing, authorization, and the result of a no-op revoke. Nothing an agent needs to call it correctly is missing.

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 meaning by stressing that revoke_key is the writer's key and that the short code cannot revoke. The schema's own parameter description already says this, so the description is reinforcing rather than adding new information.

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 (destroy) and resource (content stored by handoff_put), and explicitly scopes it as immediate and independent of TTL or fetch status. This distinguishes it cleanly from handoff_get and handoff_put without opening their schemas.

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 an explicit trigger condition ('the moment someone says they sent the wrong thing, or changed their mind') and an explicit authority rule (only the writer can revoke, not the fetcher). It also clarifies the edge case where revoking a gone item is not an error.

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