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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, so the mutation and open-world nature are already structured. The description nevertheless adds meaningful behavioral context beyond them: consent gating before invocation, the once-only semantics, and what the call yields (the opening line). It does not cover auth requirements or return format in more depth, so a 4 rather than 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?

The core action is front-loaded in the first clause, and each following sentence carries distinct operational content (consent, exception, follow-up). It is slightly dense and runs long in the middle sentence, but nothing is redundant padding.

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 correctly compensates by stating what is returned (the contact's opening line / task background) and how to act on it. Consent flow and sibling routing complete the picture. Minor gaps remain around file-saving behavior tied to accept_files.

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 'from' and 'accept_files' are already documented in the schema, including the optionality of 'from'. The description adds no syntax or semantics beyond that (e.g. it never mentions accept_files), 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?

States a specific verb and resource ('Accept a contact's invitation: join the room they opened and return their opening line'), and explicitly contrasts its role with siblings agenthop_join and agenthop_say. An agent can distinguish it from agenthop_decline and agenthop_join 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?

Gives an explicit precondition ('Tell the user about the invitation first and call this only once they agree'), a documented exception ('unless they said beforehand to accept anyone who calls'), and downstream routing ('treat the opening line as with agenthop_join; confirm via agenthop_say'). This is a full when/when-not/alternative specification.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is already covered. The description adds valuable handshake semantics beyond the annotations: the other side responds with a goodbye before both sides finish, which tells the agent this is an interactive two-step termination rather than a fire-and-forget call.

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 sentences, zero waste, with the core action ('End the conversation') front-loaded ahead of the optional modification and the handshake behavior.

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 one-optional-parameter tool with no output schema and full annotation coverage, the description covers the action, the optional input, and the termination handshake. It could mention whether the call blocks until the other side responds, but nothing critical 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 coverage is 100% and the single 'text' parameter is documented as 'A parting line' in the schema. The description's 'optionally with a parting line' confirms optionality but adds no format, length, or syntax detail beyond the schema. 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?

States a specific verb and resource ('End the conversation') with a clear scope that cannot be confused with siblings like agenthop_say or agenthop_wait. An agent can immediately tell this terminates the session rather than sending a message.

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 description — call it when you want to end the conversation — but no explicit when/when-not guidance or named alternative (e.g., use agenthop_say for a final message without ending) is provided. Adequate but leaves routing to inference.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety and mutability profile. The description adds return-content context by listing the four pieces of information produced, but it does not describe formatting, ordering, or any behavioral constraints beyond what annotations provide.

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 a single, front-loaded sentence that lists exactly what the tool returns. Every clause contributes information, and there is no redundant or filler text.

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 parameters, the description must carry the burden of explaining what is returned. It does list the main return items, which is sufficient for a simple listing tool, though it could be more complete by implying the structure or format of pending invitations and the contacts list.

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 are no parameter semantics to explain. Per the scoring rule, a zero-parameter tool receives a baseline of 4, which is appropriate here.

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 uses a specific verb (List) and enumerates the resources returned: contacts with name and fingerprint, the machine's own fingerprint, inbox online state, and pending invitations. It clearly states what the tool does, but it does not differentiate from sibling tools like agenthop_status, which may also report local state.

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 provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, context of use, or point to related sibling tools. Usage is only implied by the tool name and the listed data.

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 cover the safety profile (non-read-only, open-world, non-idempotent, non-destructive), and the description adds real workflow behavior: a pairing code is produced, it must be relayed to the user, and background is transmitted as the opening line to the other side. It could still note whether repeated calls create duplicate rooms, but it adds genuine context 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?

Two tight sentences with the primary outcome front-loaded and no filler. Density is high 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?

With no output schema, the description supplies the key return value (the pairing code) and the surrounding flow, which is what an agent needs to call this correctly. Minor gaps remain around failure cases or re-invocation, but the essentials are covered.

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 already 100%, so the baseline is 3, but the description adds semantics the schema lacks: background is not just a topic label, it becomes the other party's opening line and a mutual identity check. accept_files is left to 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?

'Open a room and return its pairing code' gives a specific verb, resource, and return artifact, and explicitly names the counterpart command (agenthop_join) so the agent can distinguish it from its pairing sibling.

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 the required downstream action ('hand the whole code to the user to pass on') and routes the other side to agenthop_join, which is explicit context. It stops short of stating when this should NOT be used (e.g. when you should instead accept a pending invite), so it is strong but not exhaustive.

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 non-readonly, non-idempotent and open-world behavior, so the description only needs to add value. 'They know right away' usefully discloses the immediate-notification side effect on the other party, a real behavioral trait not encoded in 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?

Two short, front-loaded sentences with no wasted words; the core action leads and the behavioral note follows. The second sentence is slightly colloquial but still earns its place by conveying notification timing.

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 simple two-parameter tool with no output schema, full schema coverage and meaningful annotations, the description covers what is needed to call it correctly. Missing only explicit routing to the accept/wait alternatives.

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 both parameters (from, reason) are fully documented with examples in the schema itself. The description only restates that a reason is optional, adding no syntax or format detail beyond the schema — 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?

States a specific verb plus resource ('Decline a contact's invitation'), which cleanly separates it from the sibling agenthop_accept. It stops short of explicitly naming that sibling as the counterpart choice, so it is clear but not fully differentiated in-text.

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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of the alternative (agenthop_accept, agenthop_wait). 'They know right away instead of waiting' reads as a benefit statement rather than a condition that selects this tool over a sibling.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuine state-change context the annotations cannot convey: invitations stop being taken and the contact can no longer be invited by name.

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 tight sentences with no filler, and the core action is front-loaded before the consequence detail. Every clause earns its place.

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 output schema, the description covers the action and its lasting effects adequately. Minor gaps remain around whether the deletion is reversible or requires confirmation.

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 sole parameter (name) is fully documented there, so the description need not compensate. It adds no syntax, format, or lookup semantics beyond what the schema provides, matching the baseline for high-coverage schemas.

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 ("Delete a contact"), which is unambiguous and readily separable from siblings like agenthop_save_contact and agenthop_contacts. It does not, however, explicitly name an alternative tool or scope the deletion further.

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?

No guidance on when to reach for this tool versus alternatives such as agenthop_save_contact or agenthop_bye, and no prerequisites stated. The consequences are described, but the selection context is left entirely to inference.

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 annotations covering safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description adds real behavioral context beyond them: the failure mode if the peer agent is not running, that "background" is delivered as the opening line, and the follow-up workflow. It doesn't discuss delivery semantics like retries or timeouts.

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-loaded with the action, then preconditions, failure behavior, and next step in a compact three-sentence block. Slightly dense clause chaining, but no sentence 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?

No output schema exists, so the description usefully covers the key return-relevant behavior (you are told when the peer isn't running) and the follow-up tool. Sufficient for a 3-param invitation tool, though it omits any mention of how an accepted invite is confirmed.

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 meaningfully elaborates "background" (it becomes the opening line on acceptance) rather than merely restating the schema. "accept_files" is left to the schema, which is acceptable.

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 ("Invite a contact to talk") and adds the distinguishing condition "with no pairing code to pass on," which implicitly contrasts with the pairing-code path (e.g. agenthop_join). It stops short of naming the sibling it is not, so differentiation is inferred rather than stated outright.

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 a clear precondition ("Their agent must have agenthop running right now") and an explicit next step ("use agenthop_wait to wait for them to join"). It does not state when not to use it or which sibling covers the pairing-code case, but the when-to-use context is solid.

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 a non-read-only, non-idempotent, open-world call. The description adds context annotations cannot convey: that the call blocks until the counterparty's opening line arrives, and that the channel only opens after a one-line confirmation. This two-phase handshake behavior is genuinely useful and non-obvious.

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 action ('Join the other side's room...') and packs the workflow into two sentences with no filler. The second sentence is dense and slightly run-on, which keeps it from a 5.

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, so the description correctly states what is returned (arrival of the opening line) and what triggers the channel to open. Combined with annotations covering the safety profile and a fully documented schema, an agent has enough to call this correctly.

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 both parameters (code, accept_files) are already documented in the schema, including the file-saving default. The description only restates 'pairing code' in prose and adds nothing about format or the accept_files toggle, 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?

States a specific verb (join) and resource (the other side's room) plus the credential it consumes (pairing code). An agent can distinguish it from siblings like agenthop_accept, agenthop_create, or agenthop_invite 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?

Gives an explicit conditional protocol: verify the incoming opening line against your context, and if it does not match, ask the user and do not reply. It also names agenthop_say as the tool to confirm with. It lacks a hard statement of when not to use it at all (e.g., when already joined), so it falls just short of a 5.

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 cover safety (readOnly=false, destructive=false, idempotent=false), so the bar is lower, yet the description still discloses non-obvious behavior: the contact record enables name-based invites with no pairing code, and reciprocity is required for invitations to succeed. Nothing contradicts the annotations; it simply does not discuss idempotency of repeated saves.

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, front-loaded with the action, then the consequence for invites, then the precondition. Every sentence carries information an agent needs; 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 one-parameter, non-destructive write with no output schema, the description covers the action, the downstream benefit, and the reciprocity precondition. It omits only what a save returns or whether re-saving overwrites an existing name, which are minor gaps.

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?

Only one parameter and schema coverage is 100%, with the schema already giving a good example ('alice or Sam's laptop'). The description references inviting 'by name' but adds no formatting or uniqueness rules beyond the schema, so it sits at the baseline for a fully documented single parameter.

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 ('Save the other side of this conversation ... as a contact') and clarifies the downstream effect on agenthop_invite, so the agent understands what this produces. It does not explicitly contrast itself with siblings like agenthop_contacts or agenthop_forget_contact, but the purpose is unambiguous.

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?

Specifies the timing window ('ongoing or just finished') and states a hard prerequisite: the counterpart must also save you, otherwise invitations 'will not be taken.' That is real routing-relevant context. It stops short of naming when not to use the tool or an explicit alternative.

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?

The description adds behavioral context beyond the annotations: it returns whether the message was delivered, supports multi-line text, and notes that the joining side's first line is a confirmation. These details help an agent understand the tool's side effects and response, though it doesn't cover auth, rate limits, or idempotency (which annotations already partially address).

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 short and front-loads the core purpose and delivery return. It includes a specialized note about the joining side's first line and routes to two alternatives, with little wasted wording. It could be slightly more polished, but every sentence contributes.

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 the tool's simplicity (one required parameter, no output schema, annotations covering safety), the description covers purpose, usage alternatives, return value, and multi-line behavior. It leaves minor assumptions (e.g., what 'the other side' means) to context, but is nearly complete for correct invocation.

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?

With 100% schema coverage, the schema already documents the single 'text' parameter as 'What to say'. The description adds that the text 'may span several lines,' which is useful semantic detail not present in 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 states a specific verb ('Say') and resource ('something to the other side'), making the tool's purpose clear. It distinguishes itself from two siblings (agenthop_working for receipts, agenthop_bye to finish), though it does not differentiate from others like agenthop_send_file.

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 names alternatives and the conditions for using them: 'Use agenthop_working for receipts and agenthop_bye to finish.' This gives clear routing guidance for two related tools. However, it does not specify when not to use this tool versus other messaging or file-transfer siblings.

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=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds substantial value beyond that: the 512 KiB cap, end-to-end encryption of contents and name, relay blindness, and the conditional disk-persistence behavior on the recipient side. It stops short of covering error/return behavior, but the added behavioral context is rich.

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 purpose and size limit, then the encryption guarantee, then recipient behavior. No wasted words.

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, no-output-schema tool whose annotations already carry the safety profile, the description covers size limits, privacy guarantees, and recipient-side behavior. Nothing essential 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% for the single 'path' parameter, so the schema already documents it. The description adds no further parameter syntax, format, or constraints beyond the implicit file-size limit. Baseline 3 is correct 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 ('Send a file') plus an important constraint (at most 512 KiB). This clearly distinguishes it from the sibling agenthop_say messaging tool.

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 context is implied by the description ('send a file to the other side'), but it never states when to prefer this over agenthop_say or any prerequisite for the recipient to receive files. No explicit alternatives or exclusions are given.

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 readOnly, idempotent, and non-destructive, so the safety bar is lower. The description adds genuine value by enumerating the data actually returned (step, pairing code, log path, identity, inbox, invitations), which matters because there is no output 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?

A single dense sentence that front-loads the primary purpose (conversation state) before the secondary machine-identity data. Every clause carries information, though the semicolon-joined list is compressed.

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 carries the burden of describing return content and does so reasonably well, covering both conversation and machine-level state. Complete enough for an agent to know what a call yields.

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 per the rubric this earns the baseline 4. There is nothing for the description to disambiguate.

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 enumerates the distinct resources it surfaces: current step, pairing code, log location, machine identity, inbox, and pending invitations. This clearly separates it from siblings like agenthop_contacts or agenthop_wait, though it never names an alternative explicitly.

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 – the framing "where the current conversation is" suggests consulting it for state checks, but there is no explicit when-to-use, prerequisites, or comparison to siblings such as agenthop_wait or agenthop_contacts. Adequate but with a clear gap.

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, openWorldHint=true, non-idempotent, and non-destructive, so the safety profile is covered. The description adds rich context beyond that: it's a blocking wait, returns 'everything new since' including the peer's progress state, and is meant to be re-called on timeout. It doesn't disclose timeout defaults (schema does) or rate limits, but the core behavior is well described.

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?

Packed into three tight sentences with no filler, each carrying distinct information: what it waits for, what it returns, and the retry/no-conversation cases. The return condition is front-loaded in the first sentence.

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 blocking wait tool with no output schema, the description covers the essential aspects: trigger (peer action or timeout), return payload (new messages plus progress), retry guidance, and idle behavior. An agent can call this correctly without further information, though the exact message format is left implicit.

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 single timeout_seconds parameter is fully documented in the schema (default 50, max 290). The description does not restate or clarify the parameter, so baseline 3 is 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 action (wait for the other side) and precisely defines the return condition (only when it is your turn or timeout). This clearly distinguishes it from siblings like agenthop_say, agenthop_working, and agenthop_status, which all take action rather than block for inbound events.

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 says when to call again (if nothing came in time) and what happens when no conversation is active (waits for invitations). This gives an agent the full lifecycle of the call and the retry loop, with no ambiguity about when to use it versus siblings.

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 readOnly=false, openWorld=true, idempotent=false; the description adds real context beyond them by explaining the observable effect on the peer (they see progress and wait instead of assuming you dropped). It does not mention what happens on repeat calls or any rate/permission constraints, which the non-idempotent hint hints at.

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, front-loaded with the core action, then the rationale, then the timing instruction. Every sentence contributes and nothing is padded.

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-optional-param, no-output-schema tool with annotations already covering safety, the description covers what it does, when to call it, and why it helps. The only minor gap is repeat-call behavior (relevant given idempotent=false).

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?

Only one optional parameter, and the schema covers it at 100% coverage with its own example. The description adds no format or syntax guidance for 'text' beyond what the schema already provides, so the baseline 3 is 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: 'Send a receipt' that tells the other side you got their line and are working on it. It implicitly distinguishes itself from a reply tool by contrasting 'progress rather than a line that needs an answer', but never names a sibling (e.g. agenthop_say) explicitly.

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 a clear trigger: 'Call it right after a line arrives, before starting the work.' That is actionable context. However, it names no alternatives or when-not-to-use conditions, so the routing guidance is contextual rather than exclusive.

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