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, 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?

No annotations are provided, so the description carries the full burden. It usefully discloses that the tool opens the 1:1 conversation iff needed before sending. However, it does not describe error behavior, ambiguous recipient handling, authentication needs, or any side effects beyond opening the conversation.

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?

One tight sentence delivers the action, the automatic open behavior, and the non-obvious `to` value formats. There is no redundant wording 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 simple two-parameter send tool, the description covers the key operational fact (auto-open) and target resolution formats. It does not specify return values or failure modes, but the operation itself is clear enough for an agent to invoke correctly in most cases.

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 gives only type string for both parameters, with 0% coverage. The description adds real meaning by explaining that `to` accepts npub, hex, email, or exact display-name. The `text` parameter is left implicit, but its purpose as the message body is obvious from context.

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 precise action, sending a direct message to a person, and the resource (a 1:1 conversation). It also distinguishes itself from sibling tools like buzz_dm_open and buzz_dm_read by stating it sends and auto-opens the 1:1 when needed.

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 usage context clear: use this when you want to send a DM, and it will create/open the conversation if necessary. It does not explicitly name sibling alternatives or state when not to use it, so it falls 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 transparency burden. It usefully discloses that @Name mentions are resolved to p-tags and trigger agents, and that attachments are uploaded from a local path. However, it does not cover permissions, visibility, or message persistence, and no output/return behavior is 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?

Three concise, front-loaded sentences with no filler. The core action comes first, followed by the important mention behavior, then the optional attachment detail. 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 simple posting tool, the description covers the primary action, the mention mechanism, and the attachment option; the schema supplies required fields and size caps. It doesn't describe return values or channel identification details, but those are not critical 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 schema only documents the attachment parameter, so the description adds meaning to text (message content, @Name mention syntax) and channel (the target channel). The attachment parameter is already well described in the schema, so the description's repetition is acceptable. Some detail about how to specify the channel (name vs ID) is still missing.

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 and target: 'Post a message to a channel.' It distinguishes itself from siblings like buzz_dm_send and buzz_react through the explicit channel context and the detail about mentioning agents.

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 explains when to use the tool: to post a message to a channel, and it adds specific guidance about using @Name to trigger an agent. It does not explicitly name excluded alternatives, but the channel-vs-DM distinction is strongly implied by the sibling tool names.

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 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 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.