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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety and locality are covered. The description adds valuable behavioral context by disclosing what is actually surfaced — connection mode (peer-to-peer vs relay), outbox backlog, and peer counts — which is meaningful diagnostic information beyond the annotations.

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?

A single sentence with no filler, front-loaded on the tool's identity and immediately followed by the specific data points returned. Every clause carries 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?

With no output schema, the description usefully enumerates the returned data points, which is exactly what an agent needs for a zero-param status read. It omits freshness/caching behavior but is otherwise complete for a tool this simple.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-param tool applies. The enumerated return fields are informative but not parameter guidance.

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 ("Show") and a precisely scoped resource ("this WokiToki identity, network connection state, pending outbox size and peer counts"). It is clearly distinguishable from the messaging siblings, though it never names wokitoki_list_peers, which overlaps on peer information.

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?

Usage is only implied: this reads as a diagnostic/health-check tool, so an agent can infer it is the right call before sending or when verifying connectivity. There is no explicit statement of when to use it instead of wokitoki_list_peers for peer data, and no prerequisites or exclusions.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered, but the description adds real value beyond them: the enumerated delivery states, the specific claim that read state is untouched, and a prompt-injection warning that received text is untrusted. It omits ordering/pagination behavior, so it is not 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?

Three short sentences, each carrying distinct information, with the core action front-loaded ahead of the two caveats. No filler or repetition.

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-optional-parameter read tool with no output schema, the description covers scope, side effects, result statuses, and a security caveat. Nothing critical is missing, though result ordering and pagination behavior go unmentioned.

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 both parameters (peer, limit with default and bounds) are already fully documented in the schema. The description adds no parameter-level meaning, so the baseline of 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?

States a specific verb and resource ("List recent messages") and adds scope ("in both directions"), which an agent can act on directly. It does not explicitly distinguish itself from the sibling wokitoki_read_inbox, which is the closest alternative, so it falls short of a 5.

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?

Usage is implied rather than stated: the agent can infer this is the non-mutating way to view recent traffic, and "Does not change read state" quietly signals the difference from read_inbox. There is no explicit when-to-use, when-not-to-use, or named alternative, so it stays at minimum viable.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: only 'active' peers can receive messages, and pairing/approval are out-of-band via the CLI. It does not describe the shape of the returned peer records, but that is the main remaining gap.

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 short sentences, each carrying distinct information, with the core purpose front-loaded. Nothing is redundant with the title or schema, and the constraints follow logically.

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 read-only, single-optional-parameter list tool with annotations covering safety and no output schema, the description supplies purpose, state semantics, and the out-of-band pairing workflow. Only the return payload's contents are unaddressed, which is a minor gap given there is no output schema to lean on.

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% and the single 'state' parameter is documented with an enum in the schema. The description mentions states indirectly through the 'active' remark but adds no filtering syntax or default behavior beyond the schema. Baseline 3 is appropriate 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 and resource ('List agents this machine is paired with'), scoped to a clear domain. It is easily distinguished from siblings like wokitoki_send_message and wokitoki_read_inbox, which act on messages rather than the peer roster.

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 clear context and an explicit exclusion: pairing and approval happen through the human-facing CLI, not this tool. It also explains the consequence of the 'active' state, which guides filtering. It stops short of naming a specific alternative sibling for related tasks, so it is clear but not fully routing.

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?

Annotations declare readOnlyHint=false, so the description correctly discloses the mutating side effect ('mark them read') and adds valuable security context that structured fields cannot: the message text is untrusted agent data and must not be treated as instructions. It omits one nuance — the schema's markRead parameter allows suppressing the read-marking, while the description states it unconditionally.

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 sentences, both front-loaded: the operation first, then the prompt-injection warning. Neither is padding, and the highest-risk guidance is stated without preamble.

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 zero-required-param inbox reader with no output schema, the description covers the mutation, the untrusted-content hazard, and the implicit filtering. It could say more about the returned message shape or ordering, but annotations plus the schema carry most of the remaining burden.

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 peer, limit, and markRead are already fully documented in the schema. The description adds no syntax, default, or filtering detail beyond it, making the baseline 3 appropriate.

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: 'Return unread messages received from paired agents and mark them read.' An agent can tell this is an inbox-drain operation. It does not, however, name or contrast itself with the sibling wokitoki_list_messages, so the boundary between the two is left to inference.

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?

Usage is implied by the 'unread inbox' framing — you call this to consume new messages rather than browse history. But there is no explicit when-to-use/when-not or pointer to wokitoki_list_messages as the alternative for already-read or historical messages, which is the exact ambiguity a sibling list creates.

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?

Goes well beyond the annotations by disclosing outbound data egress ('the text leaves this machine'), a safety directive about secrets/credentials, and the asynchronous delivery lifecycle ('state becomes "delivered" once the peer's bridge confirms receipt'). Annotations only give safety/idempotency hints; the description supplies the operational consequences an agent needs.

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 earning its place: capability, safety constraint, return/delivery semantics. The core action is front-loaded in the first clause with no preamble.

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, but the description compensates by naming the return value (message id) and the follow-up verification path. Pairing prerequisites, safety caveats, and delivery-state semantics are all covered for a simple 3-param tool.

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 all three parameters are already documented in the schema, making 3 the baseline. The description restates the 'to' addressing mode (name or device id) but adds nothing about replyTo or the 16000-char text limit 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?

Specific verb+resource ('Send an ... encrypted text message') with scope qualifiers (already-paired, active peer, by name or device id). It is clearly distinguishable from the list/read siblings which retrieve rather than transmit.

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?

States the precondition that the peer must be already paired and active, and names wokitoki_list_messages as the way to check delivery state, which routes the agent to the right sibling. It does not, however, describe what to do if the peer is not paired/active or name any alternative send path.

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