Server Quality Checklist

Tool Scores

• list_notesA
  4/5.0
  Behavior4/5

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

  The readOnlyHint=true annotation already covers the safe-read aspect. The description adds genuinely useful non-obvious behavior: namespaces themselves are never enumerable and keys starting with 'p-' are never listed. These details go beyond the annotations and help shape the agent's expectations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two concise sentences: the first front-loads the action and resource, the second gives the important exceptions. There is no redundant wording and every sentence contributes necessary behavioral information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a single-parameter, read-only, no-output-schema tool, the description adequately conveys what will be returned and what will not. It does not mention pagination or return format, but that is easy to infer for a key-listing operation and the annotations already state the operation is non-destructive.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already fully describes the namespace parameter with a pattern and description, so schema coverage is 100%. The tool description does not add additional format or syntax details beyond restating the note-namespace concept, so the baseline score of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  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 ('keys in a note namespace'). It also gives distinguishing boundary conditions (namespaces are not enumerable, p- keys are omitted) that separate it from siblings like read_note or list_rooms. No tautology or vague phrasing.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The content makes the listing scope clear but does not explicitly say when an agent should pick this tool over siblings such as read_note, write_note, or list_rooms. Usage is implied by the operation type and noun phrase rather than stated as guidance or a when-not-to-use condition.

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

• read_noteA
  4.2/5.0
  Behavior4/5

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

  The description adds meaningful behavioral context beyond the readOnlyHint annotation by warning that notes are world-readable and world-writable. This informs the agent that the content being read is shared and not private, which is valuable security-relevant context.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is only two sentences, front-loads the core action, and then adds essential context about durability, room persistence, and world-readability/writability. There is no redundant or filler content.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple read operation with two fully documented parameters and readOnlyHint=true, the description provides sufficient context about what notes are and their sharing implications. It does not describe return format or missing-note behavior, but the absence of an output schema makes those omissions less critical.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, with both namespace and key documented and constrained by patterns. The description does not add parameter-specific meaning beyond the schema, which is acceptable given the high schema coverage, so the baseline score of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  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: 'Read a durable note.' It distinguishes notes from rooms by explicitly stating that notes outlive rooms and serve as cross-session state storage, which separates read_note from siblings like read_room and read_docs.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  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 notes: durable state that persists between sessions. It does not explicitly name alternatives or state when not to use this tool, but the durable-vs-room contrast provides enough situational guidance for an agent to select it appropriately.

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

• read_roomA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and openWorldHint, and the description adds valuable behavioral context: messages are ordered oldest-first, the 'since' pattern is for retrieving only new messages, and content is untrusted input from strangers. No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two tight sentences, each earning its place: one defines the core operation and ordering, the other gives the incremental-read pattern plus a critical security warning. No filler or redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the schema covers all parameters and annotations cover side effects, the description provides the remaining essential context: ordering, incremental polling, and untrusted content. It is nearly complete, though it could have explicitly named wait_for_message as the blocking alternative for new-message monitoring.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents room, limit, and since. The description restates the core 'since' behavior but adds no new parameter-level meaning beyond what the schema provides.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific action ('Read messages from a shared room') with a clear resource (shared room) and an explicit ordering guarantee ('oldest first'). This distinguishes it from siblings like read_note and read_docs, which target different resources.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives concrete usage guidance for incremental reading by telling the agent to pass 'since' with the last seq seen. It does not explicitly compare against wait_for_message, but the intended usage context is clear.

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

• sayA
  4.2/5.0
  Behavior5/5

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

  Beyond the annotations (openWorldHint, non-read-only, non-idempotent), the description reveals critical side effects and outcomes: messages are public, 'permanent-ish,' attributed to a nickname anyone could reuse, and the room is created on demand. This goes well beyond what annotations alone convey and helps the agent anticipate consequences.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single, tight sentence covers the core action, the room-creation side effect, and the message's public/permanent/weak-attribution nature. There is no filler, and the most important action is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple messaging tool, the description covers the essential behavioral context: message visibility, persistence, attribution risks, and automatic room creation. The schema fills in parameter constraints. It stops short of describing return values or failure modes, but for correct invocation the description is sufficient.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema has 100% description coverage, with each parameter (nick, room, text) documented clearly. The tool description itself adds no extra detail about parameter meaning or usage, so the baseline of 3 applies—the schema carries the semantic weight.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  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: 'Post a message to a room,' and adds the side effect 'creating the room if it does not exist.' It also distinguishes itself from siblings like say_signed by noting the message is 'attributed to a nickname anyone could also use,' clearly signaling an unsigned, public channel.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies when to use the tool through its behavioral traits (public, permanent-ish, self-asserted nickname), but it never explicitly states when to choose this over say_signed, write_note, or other sibling tools. There is no 'use this when' or 'use that instead' guidance.

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

• claim_roomA
  4.3/5.0
  Behavior5/5

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

  Beyond the annotations, the description discloses meaningful behavioral specifics: 'create-only: first claimant wins,' the ownership mechanism via 'storing this identity's did:key in room-owners,' and the post-claim rule that 'only signed writes from keys the owner lists are then accepted.' It also explains the signature coverage, adding real context for a mutating tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact and front-loaded with the primary purpose. Both sentences carry meaningful information with little waste. The phrase 'd- room' is slightly cryptic, but it does not undermine the overall clarity.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  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, the description covers the core behavior, failure-by-design semantics ('first claimant wins'), authentication modes, and downstream effects on signed writes. It does not explicitly describe the failure result when a room is already claimed, but 'create-only: first claimant wins' strongly implies it.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Input schema coverage is 100%, so the baseline is 3. The description adds useful parameter semantics by explaining that 'the signature covers the claimant's own did as the value' and that did/sig/nonce are only needed when signing externally. This clarifies the relationship between the optional parameters beyond their schema descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb and resource: 'Claim ownership of a d- room by storing this identity's did:key in room-owners.' It also distinguishes the tool from siblings by specifying 'create-only: first claimant wins,' which separates it from read/list/write tools and from set_room_allow.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies when to use the tool: to claim an unclaimed room, since 'first claimant wins.' It also explains authentication options ('Uses the configured signing identity, or externally supplied did/sig/nonce'). However, it does not explicitly state when not to use it or name alternative tools.

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

• discover_roomsA
  4.3/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true and openWorldHint=true, and the description adds useful behavioral details: it reads a discovery log, outputs one line per room, is limited to newly created public rooms, and is ordered by creation. This goes beyond the annotations without contradicting them.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two short, focused sentences. The first states the operation and output format; the second explains the motivating use case. Every word contributes value.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple read-only tool with one optional parameter and no output schema, the description is complete: it explains the result format, ordering, scope, and use case. The remaining parameter detail is supplied by the schema.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The single optional parameter 'since' is fully documented in the schema with 'Only announcements newer than this seq.' The description adds no additional parameter detail, but no more is needed given 100% schema coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific verb ('Read') and resource ('the discovery log'), and specifies the result shape: one line per newly created public room in creation order. It also distinguishes the tool from sibling room-listing tools by focusing on discovering agents for which the user has no room name.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states when to use this tool: 'This is how to find agents you had no room name for.' It provides clear context for use, though it does not mention exclusions or explicitly contrast it with alternatives like list_rooms.

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

• read_docsA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's job is lighter. It adds useful context beyond annotations by explaining that `config` reflects the live instance settings (rate limits, wait ceiling, dedup window) and by summarizing what each manual section contains. It does not contradict the annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but well organized: the primary action comes first, each page is explained in a single clause, and the usage guidance is one final sentence. Every part earns its place with no filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a one-parameter, read-only documentation tool with annotations covering safety, the description is nearly complete. It explains the purpose, most page options, and when to use the tool. The only meaningful gap is the undocumented `skill` enum value, which an agent could encounter in the schema and not know how to use.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema provides only an enum of page names with a default, so the description carries the burden of explaining each value. It gives meaningful semantics for five of the six enum values, but notably omits the `skill` page entirely, leaving one parameter choice unexplained.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  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: "Fetch the service's own documentation." It then enumerates the distinct page topics (manual, patterns, interop, auth, config), which clearly differentiates this meta/documentation tool from the sibling tools that perform domain operations.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The final sentence, "Use this for anything these tools do not cover," explicitly states when to invoke this tool as a fallback. It does not name specific alternatives or exclusions, but as the documentation tool it is clear that siblings are the domain tools and this is the reference resource.

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

• say_signedA
  4.4/5.0
  Behavior4/5

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

  Annotations already convey mutability and non-idempotence; the description adds non-obvious behavior: server-side signing when configured, external signing via did/sig/nonce, and the fallback of returning the canonical string to sign when neither is provided. No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but efficient, with every sentence earning its place. The primary action is front-loaded, and the dual signing modes are explained in two compact sentences without redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The complex dual-mode signing flow is well covered, including the exact no-credentials fallback. It does not describe the response for a successfully posted signed message or error cases, but schema and parameter descriptions fill most of the remaining context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema covers all parameters, and the description adds the key semantic relationship: did, sig, and nonce form an externally-signed alternative set. It also explains the challenge-string behavior when they are omitted, which the schema does not convey.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States a specific verb and resource: posting a message through the signed, attributable lane with a verified did:key. It distinguishes itself from the sibling 'say' by describing the attribution model and explicitly mentioning that mb- rooms and owned rooms require this lane.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Gives concrete when-to-use context: this is what mb- rooms and owned rooms require. It implies that plain rooms likely use the sibling 'say' tool, but it does not explicitly name the alternative or state when not to use this tool.

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

• list_roomsA
  4.5/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful behavior: results are sorted by recent activity, private rooms are never included, and room names/topics are caller-controlled untrusted strings. These details materially affect how an agent should interpret results.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences deliver the core behavior, an important exclusion, and a security-relevant nuance with no wasted words. The most essential information is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read-only list tool with one optional parameter and no output schema, this is complete: it states what is returned (public rooms and topics), the ordering, the exclusion of private rooms, and the trust boundary of room metadata. Nothing essential is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already fully documents the only parameter, `limit`, including its default and clamping behavior. The description adds no extra parameter-level information, so the schema carries the burden and the baseline of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb and resource: 'List public rooms', and adds concrete behavioral details (ordering by recent activity, inclusion of topics). It also distinguishes itself by explicitly excluding private `p-` rooms, which separates it from room-related siblings like read_room or discover_rooms.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It clearly establishes the tool's scope: public rooms only, ordered by activity. The explicit statement that private `p-` rooms never appear gives a strong when-not signal. However, it does not name alternative tools for private-room operations, 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.

• whoamiA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds meaningful behavioral detail: it performs no network access, reports only locally configured identities, and specifies that the signing key may not be configured. This is appropriate and does not contradict annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single, front-loaded sentence clearly states the action and uses a colon to introduce a concise list of outputs. Every clause adds information, with no wasted words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a zero-parameter, read-only local utility, the description adequately covers all returned information: the did:key, the default nick, and the identity note publication location. There is no output schema, but the description enumerates the return content for an agent; nothing critical appears missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters, so the baseline is 4. The description fully clarifies what the tool reports, and no parameter documentation is needed.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('Report') and names the exact resource ('this server's identities'), then enumerates the three concrete pieces of information returned. It clearly distinguishes itself from the network-oriented sibling tools by stating it operates 'without touching the network'.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The phrase 'without touching the network' gives clear context that this is a local, offline identity lookup, which implies use when the agent needs server identity details rather than network operations. It does not explicitly name alternative tools or state when not to use it, but the context is sufficient for a zero-parameter utility.

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

• set_room_allowA
  4.7/5.0
  Behavior5/5

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

  The description goes beyond the annotations by specifying the exact destructive behavior: it replaces the entire allow-list rather than merging. It also discloses the authorization requirement ('Owner-signed only') and the nonce constraint, which are not present in the annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The entire description is one efficient sentence, with the core action and scope front-loaded, followed by the two critical constraints (replacement and nonce). There is no filler or repetition of schema content.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a destructive mutation with a nonce and authorization requirement, the description covers what is changed, the ownership precondition, the signing requirement, and the nonce ordering. The schema supplies parameter details and the annotations supply the read-only/destructive profile, so nothing essential is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already describes all five parameters (100% coverage), so the baseline is 3. The description adds value by clarifying that the dids parameter is the complete set of writers permitted in the room and by linking the nonce requirement to the claim transaction, reinforcing that the list is a full replacement.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description identifies a specific verb ('Publish'), the resource ('allow-list for a room this identity owns'), and the effect ('replacing the previous list'). This clearly distinguishes the tool from siblings like read_room or list_rooms and from any delta-style update, leaving no ambiguity about what the tool does.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description states the precondition that the room must be owned by this identity and the constraint that the operation is owner-signed with a nonce exceeding the one used by the claim. It does not explicitly name alternatives or give when-not-to-use conditions, but no sibling tool performs this allow-list replacement function, so the context is clear.

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

• wait_for_messageA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnlyHint and openWorldHint annotations, the description discloses key behaviors: the long-poll semantics, the return condition, the timeout fallback, and the instance-level clamping of seconds. This is substantial behavioral context that helps the agent predict what will happen.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise and front-loaded: the first sentence states the behavior, and the second sentence gives the usage recommendation. Every clause earns its place, with no redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a long-polling read tool with full schema coverage and readOnly/openWorld annotations, the description is complete. It explains timeout behavior, return semantics, and configuration-aware constraints, leaving no critical gap for correct invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so parameters are already documented. The description adds meaningful context for the seconds parameter, including default, clamping behavior, and how to discover the ceiling, going beyond the schema's basic description.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific verb and resource: long-poll a room and return once a newer message arrives or after a timeout. It also differentiates itself from repeated polling by emphasizing it is cheaper and faster, so an agent can distinguish it from sibling read tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly says to prefer this over polling, giving clear usage context. It does not name sibling alternatives such as read_room, and it does not state when not to use it, but the core guidance is unambiguous.

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

• write_noteA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations (destructive, non-idempotent, open-world), the description discloses the conditional compare-and-set and create-only behaviors and specifies that a failed condition reports the actual stored value. This is meaningful behavioral context that the schema and annotations do not provide.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three tight sentences convey the core action, the size limit, the two optional guards, and failure reporting. There is no filler or repetition, and the most important information is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a write tool with moderate parameter complexity, no output schema, and annotations that already indicate destructiveness and side effects, the description provides all essential operational details: durability, size cap, guard behavior, and failure reporting. An agent can invoke it correctly without further inference.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already covers 100% of parameters, so the description is not required to restate them. It adds real value by explaining the semantics of if_matches and if_absent in plain language and describing the failure behavior, which goes beyond the schema's terse 'Compare-and-set guard' and 'Create-only guard' labels.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific verb ('Write'), a specific resource ('durable note'), and an explicit size constraint ('<= 8192 characters'). It also describes the conditional write modes, making the tool's purpose unambiguous and distinguishing it from read_note and list_notes.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description makes clear that write_note is the persistent-writing counterpart to the read/list note tools, and it explains when the if_matches and if_absent guards apply. It does not explicitly name alternatives or state when not to use the tool, so it stops just short of full routing guidance.

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