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

With no annotations, the description carries the burden of behavioral disclosure. It reveals that the action is performed as the current user, depends on the user's own role, and warns that the added person can see prior channel history. This covers key side effects and permission boundaries.

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 front-loaded with the core purpose and uses dense, useful detail. The final sentence partially repeats schema property descriptions, but it also adds the 'optional' framing and permission context, so it still earns most of 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 mutation tool with no output schema, it covers the essential call context: identity, permissions, role semantics, and a privacy side effect. It does not describe error cases or return values, but those are secondary for a straightforward add-member action.

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 67%, with channel lacking a description. The description adds meaning by specifying the accepted user formats (npub/hex/display-name/email) and the optional role values with default and permission implications. This partly compensates for the undocumented channel 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?

The description starts with 'Add a person to a channel', identifying a specific action and resource, and adds the protocol context 'NIP-29 kind 9000' and 'as you'. This clearly differentiates it from siblings like buzz_remove_member and buzz_channel_members.

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 concrete conditions for use, such as 'private channels need you to be a member' and 'elevated roles need owner/admin'. It does not explicitly name alternative tools, but the permission-based guidance is clear enough for an agent to decide when invocation is appropriate.

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?

No annotations are provided, so the description carries the full burden. It does disclose the output content (display name + pubkey) and that the operation is a listing, which implies read-only behavior. However, it does not mention ordering, whether the list is exhaustive, pagination, or any authentication requirement, leaving some behavioral gaps.

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, tightly worded sentence with no filler. The verb 'List' is front-loaded, and every phrase ('known agents/people', 'display name + pubkey', 'on the relay') adds useful constraint. Nothing is redundant or wasteful.

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-parameter, no-output-schema tool, the description is largely complete: it states the action, the resource, and the fields returned. It would benefit from a brief note on whether the list includes all agents or only cached ones, and whether an empty list is possible, but these are minor for such a simple 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?

The tool has zero parameters, so the input schema is empty and schema coverage is 100%. The baseline for zero-parameter tools is 4, and the description does not need to explain parameter semantics since there are none. It correctly focuses on output rather than input.

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 ('List') and a precise resource ('known agents/people') with the specific output fields (display name + pubkey) and scope ('on the relay'). This makes it clearly distinguishable from sibling tools like buzz_whoami or buzz_channel_members without needing to inspect 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?

The description implies when to use it: whenever the agent needs the set of known agents/people on the relay. However, it does not explicitly state alternatives or exclusions, such as 'use buzz_whoami for the current user' or 'use buzz_channel_members for relay members within a channel.' The context is clear but there is no direct routing guidance.

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?

No annotations exist, so the description carries the full transparency burden. It usefully discloses the polymorphic return behavior (text for docs, saved file path otherwise) and the access precondition ('a message you can read'). However, it does not disclose file persistence/location, permission implications, or error behavior for an invalid index or missing attachment.

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, front-loaded with the action and return behavior, followed by identification and index guidance. Every sentence contributes essential invocation or selection information, 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?

For a 3-parameter read/download tool with no output schema, the description provides what an agent needs to call correctly: message identity components, index usage, and the return format. Minor omissions like supported attachment types or saved-file location do not prevent correct invocation or selection.

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 67%, leaving channel undescribed by the schema. The description adds the critical relationship 'channel + event' as the message identifier, and clarifies event as coming from buzz_read's <id>. It also reinforces the default index behavior, adding meaning beyond the raw parameter list.

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, concrete operation: 'Download an attachment from a message you can read and return it.' It clearly targets message attachments, distinguishing it from sibling tools like buzz_read (messages) and buzz_post (messages). The parenthetical output difference (text extraction vs saved file path) further clarifies the tool's resource and behavior.

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 clear usage context: the message is identified via channel + event, with event sourced from buzz_read's <id>, and index sels attachment among multiple. It does not explicitly contrast with possible direct-message attachment flows or name alternatives, so it stops 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?

No annotations are provided, so the description carries the full behavioral burden. The verb 'List' and the explicit output fields communicate a read-only operation and what the caller receives. It does not disclose error behavior, permissions, or detailed return structure, but for a low-risk listing tool the core behavior is clear enough.

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 one concise sentence with no wasted words. The action is front-loaded, and the parenthetical output summary provides useful detail without bloating the definition.

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 one required parameter and no output schema, the description covers the core action and the fields returned. The main gaps are the channel identifier format and any usage or error context, so it is minimally complete but leaves some details for the agent to infer.

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 provides only a string property named 'channel' with no description, so the description must compensate. It clarifies that the parameter identifies the channel whose members are being listed, but it does not specify the expected format such as channel name vs ID, or any constraints. This is minimal value beyond the property name itself.

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?

Clearly identifies a specific read operation — listing the members of a channel — and specifies the returned fields: display name and owner/member role. This also distinguishes it from sibling tools like buzz_channels, which lists channels, without ambiguity.

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 states exactly what the tool does, so an agent can infer when to use it: whenever it needs the member list and roles for a channel. It does not explicitly name alternatives or exclusions, but the intended use case is unambiguous and unlikely to be confused with the sibling tools.

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?

No annotations are provided, so the description carries the full behavioral disclosure burden. The verb 'List' clearly implies a read-only, non-mutating operation, which is helpful, but the description does not mention whether private or archived channels are included, how results are ordered, or what fields are returned. For a simple parameterless list tool this is adequate but has clear gaps.

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 eight-word sentence with no filler, unnecessary qualifications, or repetition. The key information is front-loaded and every word 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 zero-argument listing tool, the description is largely sufficient: it names the operation, the resource, and the scope. However, with no output schema, it leaves return-value details implicit (e.g., whether channel names or IDs are returned), and it does not explicitly clarify that 'channels' excludes direct messages, though the sibling buzz_dm_list suggests this. Minor gaps given the low complexity.

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 input schema is empty with zero parameters and 100% schema description coverage, so there are no parameter semantics for the description to clarify. Following the baseline rule for zero-parameter tools, the description does not need to compensate for anything.

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 a clear resource ('channels in the Buzz workspace'), making the tool's function immediately identifiable. It also differentiates from sibling tools such as buzz_dm_list (direct messages) and buzz_channel_members (member lists) without needing to mention 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 provides no guidance on when this tool should be chosen over alternatives, when not to use it, or which sibling might be more appropriate in other scenarios. It is a standalone statement of the action rather than usage context.

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 behavioral disclosure burden. It transparently flags the operation as 'Destructive,' states that it acts 'as you' (identity-bound), and describes the role-based relay restriction. This goes well beyond the bare schema and gives the agent a realistic safety profile.

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, front-loaded with the action and destructiveness, and every clause earns its place. The critical identifiers and authorization condition are packed in without redundancy or 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 destructive tool with no output schema and no annotations, the description covers the essential operational context: what action is performed, how destructive it is, who may perform it, and how to specify the target. It does not explain post-deletion behavior, but that is reasonably inferable from 'delete' and would not block a correct call.

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 only 50%, with `channel` lacking a description. The description compensates by explaining the composite identity: 'Identify the message by `channel` + `event`' and clarifying that `event` is the `<id>` from buzz_read. It adds cross-tool context that the schema alone does not provide.

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: 'Delete a message in a channel', and adds a protocol identifier (NIP-29 kind 9005). This clearly differentiates it from sibling tools like buzz_post, buzz_react, or buzz_remove_member, all of which have different actions or targets.

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 clear context for when deletion is permitted: 'the relay only allows it where your OWN role permits (owner/admin)', and instructs how to identify the target message via channel + event. It does not explicitly name alternatives or exclusions, but none are necessary since no sibling performs message deletion.

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 burden of behavioral disclosure. 'List' indicates a read-only operation, and the stated output fields clarify what is returned, but the description does not mention response format, ordering, pagination, or authentication/authorization requirements.

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 delivers the purpose and the returned content with no wasted words. The key idea is front-loaded and the parenthetical gives the essential output detail.

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?

The tool is simple (zero parameters, no output schema), and the description supplies the main missing context: what items are listed and what each list entry contains. It could add richer guidance on using the returned dm channel id with sibling tools, but nothing critical is missing for basic 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?

The tool has zero parameters and the schema is empty, so there is little for the description to add. The description's 'your' scoping is a small but useful clarification beyond the empty schema; baseline 4 applies for a no-parameter tool.

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') with a clear resource ('your direct-message conversations') and states the key returned fields ('other participant + dm channel id'). This distinguishes it from sibling tools like buzz_dm_read, buzz_dm_open, and buzz_dm_send, which act on individual DMs rather than listing 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 phrase 'List your direct-message conversations' provides clear context: use this tool to enumerate existing DM conversations before reading or sending to one. It does not explicitly name alternatives or exclusion conditions, but the intent is unambiguous among the sibling tools.

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 transparency burden. It discloses the dual 'open or find' behavior and the returned channel id, but it does not say whether 'open' can create a channel, what happens if the person cannot be found, or any permission/rate-limit implications.

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 front-loaded sentence that covers the action, resource, return value, and required parameter format. There is no filler or redundancy.

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 tool with no annotations and no output schema, the description covers purpose and parameter semantics well. It does not elaborate on side effects or error cases, but the simple interface makes that a minor gap rather than a major omission.

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 input schema only defines 'to' as a plain string; the description adds essential meaning by specifying accepted formats: npub / hex / email / exact display-name. This compensates for the 0 schema description coverage, though it could be more explicit about matching rules.

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 operation ('Open (or find)'), the exact resource ('a 1:1 DM with a person'), and the expected output ('return its channel id'). This clearly distinguishes it from sibling DMs like buzz_dm_list, buzz_dm_read, and buzz_dm_send, which do not resolve a person to a channel.

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 clearly conveys the use case: call this when you need the channel id for a 1:1 DM with a specific person. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops 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?

With no annotations, the description carries the full behavioral burden. It clearly indicates a read-only operation, which implies no destructive side effects, but it does not disclose auth requirements, error behavior, or whether reading affects read state. This is adequate but minimal.

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 efficient sentence that front-loads the primary action and immediately provides the key identification modes. Every word earns its place, with no filler or repetition of schema properties.

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?

The description covers the core identification semantics but omits the purpose of `limit`, does not clarify return value shape despite lacking an output schema, and provides no guidance relative to sibling DM tools. It is usable but has clear gaps for a tool with no annotations.

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 0%, so the description must compensate. It explains `to` as npub/hex/email/exact display-name and `channel` as a DM channel id, adding real meaning. However, the `limit` parameter is completely unexplained, leaving a clear gap for a number parameter whose purpose is not obvious.

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: 'Read a direct-message conversation.' It clearly distinguishes the tool from siblings like buzz_dm_list, buzz_dm_send, and buzz_read by specifying the DM conversation scope and the identification methods.

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 rather than explicit: it is for reading a DM conversation, but it does not say when to prefer this over buzz_read or buzz_dm_list, nor does it mention any exclusions. The identification guidance ('Identify it by to or channel') is parameter-focused, not tool-selection guidance.

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 burden of behavioral disclosure. It explicitly reveals a non-obvious side effect: the tool opens the 1:1 conversation automatically if it doesn't exist. This is useful behavioral context beyond the basic 'send' verb, though it doesn't discuss permissions or failure modes.

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 dense sentences with no filler. The action and key behavior are front-loaded, followed by compact parameter guidance. 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 simple 3-parameter tool with no output schema or nested objects, the description covers purpose, recipient resolution, body parameter, alias behavior, and the auto-open side effect. An agent has enough to select and invoke this tool 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 only 33%, but the description compensates well: it explains `to` accepts npub/hex/email/exact display-name, defines `text` as the message body, and clarifies that `message` is an accepted alias. This adds meaning well beyond the raw schema and covers all parameters.

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 ('Send a direct message to a person') plus the key behavior of opening the 1:1 if needed. This distinguishes it clearly from related tools like buzz_dm_open and buzz_post, so an agent understands what this tool uniquely does.

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 makes the use case clear: sending a direct message to an individual, with no need to pre-open the conversation. It doesn't explicitly name alternative tools, but the 'to a person' and 'opens the 1:1 if needed' language provides enough contextual guidance for selection.

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 fully carries behavioral disclosure. It explicitly states 'Read-only; no writes,' explains that it opens a brand-new node:https socket rather than using the shim's normal transport, and discloses that write-health is honestly reported as unverified when no real writes have occurred. It also advertises its limitation as connector-side only.

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 long but information-dense, front-loading the core purpose and the key constraint before enumerating diagnostic verdicts. Minor redundancy exists ('Read-only; no writes' is stated twice in different forms), but each verdict and caveat serves a real decision-making purpose.

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 there is no output schema, the description goes beyond the minimum by explaining not only what is returned but what each outcome means and how the agent should act on it. It covers identity, pin status, relay dial URL, write-health unverifiability, and timeout defaults, making the tool safely callable without additional external knowledge.

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%: the only parameter, timeout_s, is already described as 'per-probe timeout in seconds (default 5, max 30)' in the schema. The description only restates 'Optional timeout_s (default 5),' adding no meaningful new semantic detail beyond the structured field.

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 diagnostic verb and resource: 'Diagnose why Buzz reads/posts are failing.' It clearly differentiates from all sibling read/write/status tools by emphasizing it is read-only and probes outside the normal wedged transport.

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 implies the right usage context: use when reads/posts are failing and normal transport may be wedged. It also gives a clear exclusion by noting this is 'not the authoritative relay health signal,' which helps an agent avoid over-relying on it. It does not explicitly name an alternative tool, but no sibling appears to be a diagnostic 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?

With no annotations, the description carries the full burden. It discloses that it creates a kind-9 reference pill and does not copy text, and clarifies target formats. However, it does not mention permissions, side effects, reversibility, or what the response looks like. For a mutation tool with zero annotation coverage, this is adequate but not 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?

The description is a single dense sentence that packs in the action, the distinction from copying, the parameter relationships, and target formats. It is front-loaded with the core behavior. No wasted words, though it could be broken into two sentences for readability.

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 complexity of forwarding with multiple target types and optional comment, the description covers the essential semantics. It does not describe the return value or failure modes, but for a forwarding action without an output schema, the provided information is sufficient for an agent to call it 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 75% (3 of 4 params have descriptions). The description adds meaning beyond the schema by explaining that source_channel+event identify the message, and by detailing the accepted formats for `to`. It also clarifies that comment is optional and empty allowed, which the schema already hints at. It compensates for the undocumented source_channel.

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 action (forward/quote), the resource (a message), and the key semantic distinction (references, does not copy). This clearly separates it from buzz_post, buzz_reply, and buzz_dm_send, even without naming siblings.

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 clearly explains what the tool does and how the target is specified (channel or person with multiple formats), but it does not explicitly mention when not to use it or name alternative tools. The context implies it is for forwarding rather than replying or posting fresh, but no 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?

With no annotations, the description carries the full burden, and it does exceptionally well. It discloses that the tool is NON-BLOCKING, returns immediately with a browser URL, attempts to open the browser, requires a follow-up call to confirm, and is idempotent. These are exactly the behavioral traits an agent needs to avoid misinterpreting the response.

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 dense yet tightly organized: purpose first, then usage context, then the non-blocking flow, then idempotency, then the parameter. Every sentence earns its place 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 an OAuth login tool with no annotations and no output schema, this is complete: it explains the target audience, the two-step flow, how to confirm success, idempotency, and the optional parameter. An agent has everything needed to invoke and sequence this tool 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?

The schema already documents client_id and its env fallback with 100% coverage, so the baseline is 3. The description repeats the optionality and fallback but adds no new semantic detail beyond what the schema provides.

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: 'Sign in as YOURSELF for "post as me" (Ekam wire-sign OAuth)'. It also clearly distinguishes this login flow from the CLI alternative and from verification via buzz_whoami, so an agent can identify its purpose even without opening the 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 explicitly says when to use this tool: for GUI/desktop clients that cannot run the buzz-mcp-login CLI. It also gives the full usage sequence: first call returns a URL, user approves, then call buzz_login again or buzz_whoami to confirm, plus the idempotent behavior. This is strong when-to-use and how-to-use guidance.

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 behavioral disclosure burden and does useful work: it explains how mentions are resolved (@Name to p-tag, triggering an agent) and what attachment means. It is non-obvious behavior that helps an agent predict side effects, though it does not discuss response values or rate limits.

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 earns its place: the action, the body/alias behavior, the mention/attachment details. 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 simple post tool with no output schema, the description covers the essential behavior, alias, mentions, and attachments. The main gap is lack of guidance for the `channel` parameter format and no explicit routing vs DM/reply tools, but overall it is reasonably complete.

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 covers `message` and `attachment`, but not `text` or `channel`. The description adds meaning for `text`/`message` and restates the attachment file path, but leaves the required `channel` parameter unspecified (name vs ID). It partially compensates for the 50% schema coverage but not completely.

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 'Post a message to a channel,' a specific verb and resource that clearly identifies the tool's function. This differentiates it from sibling tools like buzz_dm_send, buzz_reply, and buzz_forward, which cover other messaging actions.

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 phrase 'to a channel' establishes the core context and implies this is for channel posts rather than direct messages or replies. It does not explicitly name alternatives or state when not to use it, so it stops 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the action is a NIP-25 reaction, that it acts as the current identity, and that the default emoji is 👍. However, it does not mention side effects such as whether duplicate reactions are allowed, whether existing reactions are replaced, or what the observable result of the operation is.

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 three short sentences with every clause earning its place: protocol, required inputs, identity, and default emoji. It is front-loaded with the primary action and contains 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 simple three-parameter tool with no annotations and no output schema, the description covers the core invocation needs: action, required params, default emoji, and identity. It leaves out any indication of the return value or failure conditions, but given the low complexity this is a minor gap rather than a critical one.

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 67%, with emoji and event already described in the input schema. The tool description mostly repeats this ('target message's event id') and only says 'Needs the channel' without clarifying what kind of channel identifier should be used or where to obtain it. It does not compensate for the missing channel description 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 opens with a specific verb and resource: 'React to a message with an emoji (NIP-25).' This is unambiguous and distinguishes the tool from siblings like buzz_post or buzz_read. It also clarifies the identity aspect ('reacts as this identity') without confusing the reader.

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 explicitly states the prerequisites: 'Needs the channel and the target message's event id.' This gives clear context for when the tool can be used. It does not name alternative tools, but since no sibling performs reactions, an exclusion is not necessary.

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 for behavioral disclosure. It reveals that messages are 'recent' and that channel accepts a name or id, but it does not disclose output format, ordering, pagination, limit semantics, or any access constraints.

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 one short, front-loaded sentence with no filler. Every word contributes meaning.

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 annotations and no output schema, the description is thin. It omits limit behavior, ordering, output structure, and does not point to alternative read tools, leaving several operational gaps for the agent.

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%, and the description adds real meaning by explaining that 'channel' may be a name or id. It does not add any semantics for 'limit' (e.g., default, max, or interpretation), so compensation is only partial.

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 clearly states the action ('Read') and object ('recent messages in a channel'), and adds that the channel can be identified by name or id. It is specific enough to distinguish from DM-focused siblings like buzz_dm_read, though it does not explicitly name alternatives.

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 intended use case is implied: if an agent needs recent messages from a channel, this is the tool. However, there is no explicit guidance about when not to use it or when to prefer buzz_search, buzz_attachment_read, or buzz_dm_read.

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 of behavioral disclosure. It explicitly flags the operation as 'Destructive' and explains the permission requirement tied to the caller's role. It also clarifies the identity formats for 'user'. This is significant, actionable context beyond the definition of the operation itself.

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 with no wasted words. The core action and NIP reference are front-loaded, followed immediately by the destructive nature and user-format guidance. Every phrase 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?

The description covers the key aspects an agent needs: the action, the destructive nature, the role prerequisite, and identity formats. Given there is no output schema, the lack of a return-value note is acceptable. The only notable gap is the ambiguous 'channel' parameter, which, if clarified (e.g., pointing to a channel ID from buzz_channels), would make it complete.

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 50%: the 'user' parameter already has a description in the schema, and the tool description merely repeats those formats ('npub / hex pubkey / exact display-name / email') without adding new meaning. The 'channel' parameter has no schema description, but the description also fails to explain what a channel identifier is (e.g., channel ID, name, or NIP-29 reference). It does not compensate for the undocumented parameter, while also adding nothing new for the documented one.

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 ('Remove'), a resource ('a person from a channel'), and adds useful context with 'NIP-29 kind 9001' and 'as you'. This clearly distinguishes it from siblings like buzz_add_member (opposite action) and buzz_channel_members (viewing). The purpose is unmistakable even without opening the 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 provides clear context on when the tool can be used by stating 'the relay only allows it where your OWN role permits (owner/admin)'. However, it does not explicitly name the alternative (e.g., 'for adding a member, use buzz_add_member') or clarify when another tool would be more appropriate, so it falls just short of the strongest usage guidance.

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?

No annotations exist, so the description carries the full burden. It exceeds basic expectations by disclosing the NIP-10 threading behavior via marked e-tags (root/reply), the alias behavior for `text`/`message`, how to mention agents with @Name, and that `attachment` is a local file path to upload. It omits permission/auth requirements and return behavior, which keeps it from 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?

The description is two dense, information-rich sentences with no filler. It front-loads the core purpose, then packs prerequisites, aliasing, threading behavior, mention syntax, and attachment semantics in a logically ordered, efficient way.

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 write action with no annotations and no output schema, the description is largely complete: it identifies required parameters, tells where the event id comes from, explains the thread behavior, and covers optional fields. Minor gaps remain around acceptable channel identifiers, likely authentication/login requirements, and expected confirmation/response behavior, but an agent has enough to invoke it 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 60%, and the description adds meaning beyond the schema by clarifying that `event` is the id from buzz_read, that `text` carries the reply body with `message` as an accepted alias, and that `attachment` is a local file path. The only notable gap is that `channel`'s expected format is not specified, but the description still meaningfully compensates for schema gaps.

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: 'Reply to a message in a channel'. It adds a precise protocol-level qualifier ('threaded per NIP-10 (kind 9)') and the required context (channel + event), which clearly separates this from sibling tools like buzz_post, buzz_forward, and buzz_react.

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 clear context for when to use this tool: when replying to an existing message, requiring both `channel` and `event` (explicitly the `<id>` from buzz_read). It does not explicitly name alternative tools or say 'use buzz_post instead for new top-level messages', so it stops short of a 5, but the invocation condition is unmistakable.

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 behavioral burden. It discloses that the search covers recent messages, supports NIP-50, and has a default limit, which is useful. However, it does not clarify what 'recent' means, whether results are sorted, or what the response structure looks like, leaving meaningful behavioral gaps.

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 compact, front-loaded with the core purpose, and each sentence contributes essential information: search scope, protocol, and parameter behavior. There is no filler or redundancy.

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 search tool with three parameters and no output schema, the description covers the core calling contract: what is searched, how to scope, and the default limit. The only notable gaps are the vague 'recent' window and the absence of any result-format hints, but the core usage is sufficiently complete.

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. It explains the channel parameter as a scope filter and the limit's default of 20, adding value beyond the schema. However, it does not describe the required query parameter beyond implying it holds the full-text search terms, leaving its format and semantics partially implicit.

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 clearly states the tool performs a full-text search over recent messages across channels, with a specific protocol reference (NIP-50). This distinguishes it from sibling tools like buzz_read or buzz_channels because it is explicitly a search operation, not a read or channel-management action.

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 implies when to use the tool: when full-text search of messages is needed. However, it does not explicitly contrast with alternatives such as buzz_read for reading messages or buzz_dm_search, and it gives no 'when not to use' guidance. Usage context is present but not explicit.

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?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It does indicate a mutating action ('Override') and session scope, but it does not explain persistence, reversibility, permissions, or side effects. Given that this is a write operation, more transparency is needed.

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 sentence with no redundancy or filler. It front-loads the core action and object, making it immediately scannable.

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 low complexity (one required parameter, no output schema), the description provides enough context for an agent to understand and invoke the tool. It is slightly incomplete in terms of usage guidance and behavioral details, but adequate for the tool's simplicity.

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 only defines 'name' as a string with zero description coverage. The description adds meaning by indicating that 'name' is the session's friendly display name, which is a valuable mapping. However, it does not specify format constraints or edge cases, but for a single simple parameter this is largely sufficient.

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 ('Override') and resource ('friendly display name') with clear scoping ('this session' / 'fleet'). This clearly identifies the tool's action and makes it distinguishable from sibling tools that are primarily read-oriented.

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 usage context is implied: if you want to change the current session's display name, use this tool. However, there is no explicit guidance on alternatives, prerequisites, or when not to use 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 supplied, the description carries the full behavioral disclosure. It precisely states the effect (a replaceable-event clear of status with empty content) and the environment constraint (agent mode only, wire mode refusal). This is strong transparency for a tool of this simplicity; it doesn't clutter with less relevant details.

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, no filler. The action is front-loaded, and the protocol/mode details are packed in without redundancy.

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 no-parameter tool with no annotations or output schema, this description is complete: it states the action, the protocol behavior, and the operating constraint. Nothing an agent needs to invoke it 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 input schema has zero parameters, so there is nothing to document. The description correctly doesn't invent parameters; the baseline of 4 applies for zero-param tools.

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 names a specific verb ('Clear') and resource ('your live user status'), and anchors it in protocol detail (NIP-38 kind 30315, d=general, replaceable-event clear), which distinguishes it from siblings like buzz_status_set.

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 clearly restricts usage to agent mode and warns that wire mode cannot sign kind 30315, so the tool refuses there. However, it does not explicitly compare against alternative tools (e.g., buzz_status_set) for setting status, leaving that routing implicit.

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 behavioral burden and does reasonably well: it discloses the agent-only execution mode, the wire-mode refusal, and allows empty text. It stops short of describing success/error responses or side effects, but for a simple status-set mutation the key operational constraint is surfaced clearly.

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 compact and well-structured: action and resource first, then parameter semantics, then the critical mode caveat. Every sentence contributes necessary information without fluff 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 simple two-parameter tool with no output schema, the description is nearly complete: it names the operation, covers parameter semantics, and warns about the wire-mode failure. It could mention what happens on success or how this relates to buzz_status_clear, but those are minor gaps given the tool's simplicity.

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 baseline is 3, and the description largely mirrors the schema: 'text = the status message (empty allowed)' and 'optional emoji.' It adds protocol context and the agent-mode restriction, but no new per-parameter meaning beyond what the schema already states.

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 'Set your live user status,' a specific verb and resource, and adds protocol details (NIP-38 kind 30315, d=general) that make the operation unambiguous. The verb 'set' naturally contrasts with the sibling buzz_status_clear, so an agent can distinguish this tool's role without opening 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?

The description provides explicit when-not guidance: 'AGENT MODE ONLY — wire mode (post-as-the-user) can't sign kind 30315 yet, so it refuses there.' It does not explicitly point to buzz_status_clear as the alternative for clearing status, but the mode restriction gives clear usage context.

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 well: it explicitly states 'Read-only' and 'performs no writes', and discloses the heuristic nature ('NOT real read-state'), which implies it does not modify state. It does not cover output format or potential rate limits, but for a simple read-only tool these are minor omissions.

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 sentences with no filler. The opening phrase 'Read-only activity digest' immediately communicates the core purpose, and each subsequent clause adds necessary detail (scope, heuristic warning, no-writes guarantee). Every sentence 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 tool with one optional parameter and no output schema, the description is reasonably complete. It explains what it counts (messages and mentions), the scope (channels and DMs), the default look-back, and the non-mutating behavior. It does not detail the exact return structure, but the description's conceptual output ('how many @mention you') gives enough context for an agent to expect counts.

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% (the 'hours' parameter has a description with default 24). The description adds marginal value by tying 'hours' to the look-back window ('last `hours`, default 24'), but this is essentially echoing the schema. No additional semantic detail like range or format is provided, so a 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?

The description states a specific verb and resource: 'count recent messages from others' across 'channels and DMs', clearly distinguishing it from read/write siblings like buzz_read or buzz_post. It also immediately labels itself as a 'read-only activity digest', leaving no ambiguity about its function.

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 clear context: it is for checking recent activity (messages and mentions) with a configurable look-back window. It explicitly warns it is 'NOT real read-state', which effectively tells the agent not to rely on it for accurate read/unread state. However, it does not name alternative tools (e.g., buzz_read) or give explicit when-to-use vs when-not-to-use conditions beyond that limitation.

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. It makes the read-only nature explicit with 'Show' and specifies what will be returned. It does not discuss errors or session prerequisites, but for a zero-parameter read operation this is adequate.

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, focused sentence that front-loads the action and lists the result fields. Every word contributes, with no redundancy or 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 zero-parameter, no-output-schema tool that simply reports session identity, the description is fully sufficient. An agent can invoke it correctly with no additional information.

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 has zero parameters, so there is no parameter behavior to explain. The baseline of 4 applies because no compensation is needed.

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 ('Show') and a clear resource (CLI session's Buzz identity), and enumerates the exact contents (friendly name, npub, pubkey). This clearly distinguishes it from sibling tools like buzz_setname and buzz_channels.

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 establishes clear context: this is about the current CLI session's identity. While it doesn't explicitly name alternatives, there are no competing tools with overlapping purpose among the siblings, so the usage intent is unambiguous.

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