Server Quality Checklist

Tool Scores

• nostr_publish_text_noteA
  3.7/5.0
  Behavior3/5

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

  No annotations provided, so the description carries the burden. It explains tag assembly and the allowed kinds constraint, but doesn't disclose other traits like idempotency, rate limits, or error behavior.

  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: first states purpose, second states a key requirement. No wasted words.

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

  Completeness3/5

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

  For a 5-parameter tool with no output schema, the description is adequate but lacks details about the return value (e.g., the published event ID) or error conditions.

  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%, so the baseline is 3. The description adds minor value by noting hastags omit the # prefix, but otherwise repeats schema info.

  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 it's a convenience wrapper for publishing kind:1 text notes, distinguishing it from generic event publishing (nostr_publish_event) and other siblings.

  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?

  Mentions the NOSTR_ALLOWED_KINDS requirement, but doesn't explicitly state when to use this vs alternatives (e.g., for simple text notes vs custom kinds).

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

• nostr_query_eventsA
  3.7/5.0
  Behavior2/5

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

  No annotations exist, so the description must disclose behavioral traits. It does not mention that this is a read-only operation with no side effects, nor does it discuss authentication, rate limits, or potential errors. The word 'Query' implies reading, but it is not explicit.

  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 a single paragraph of ~40 words. It front-loads the purpose, lists filters, mentions return format, and ends with a characterizing phrase. No redundant sentences, but could be slightly more structured.

  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 9-parameter tool with no output schema, the description covers the return format, filter types, and source (configured relay pool). It mentions the limit default and maximum in the schema, but the description doesn't add pagination or error handling context. Overall adequate.

  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%, so baseline is 3. The description summarizes the filter types (kinds, authors, etc.) and adds context about NIP-01 mapping, which adds some value but does not go beyond summarizing existing 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 clearly states the verb 'Query', the resource 'events', and specifies it uses NIP-01 filters. It lists the supported filter types and calls itself 'The workhorse read tool', which clearly distinguishes it from sibling publish/decode 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 implicitly indicates this is the primary read tool for events, and there are no sibling tools that query events, so usage context is clear. However, no explicit when-to-use or when-not-to guidance is provided.

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

• nostr_publish_metadataA
  3.8/5.0
  Behavior3/5

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

  Annotations are absent, so the description must cover behavioral traits. It discloses the mandatory two-step confirmation due to the destructive nature (overwrites public profile) and the requirement for kind 0 to be in the allowed kinds list. However, it does not specify whether the update is a full replacement or partial merge, nor does it describe the response format or potential errors.

  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 concise, using two sentences to state the purpose and key behavioral aspects. It front-loads the action and uses bold for emphasis. It is efficient and avoids redundancy.

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

  Completeness3/5

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

  Given that the tool has 8 optional parameters, no output schema, and no annotations, the description covers essential behavioral constraints but omits important details such as update semantics (merge vs. replace) and return value. The user must infer behavior from external knowledge.

  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?

  Input schema covers all 8 parameters with individual descriptions, achieving 100% coverage. The tool description adds no additional parameter-level semantics beyond what the schema already provides, so the baseline score of 3 applies.

  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 that this tool publishes a kind:0 profile metadata event, using specific verb-resource phrasing. It distinguishes itself from sibling tools like nostr_publish_text_note and nostr_publish_event by focusing on profile metadata and noting that it overwrites the user's public profile.

  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 explains when to use this tool (for profile metadata) and provides important context: it always requires two-step confirmation and needs opt-in via NOSTR_ALLOWED_KINDS. However, it does not explicitly state when alternatives should be used, so it lacks full guidance for tool selection.

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

• nostr_list_dmsA
  3.9/5.0
  Behavior4/5

  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 transparently explains the decryption process (auto-selects NIP-44 or NIP-04 based on ciphertext), error handling (per-event failures), and sorting (oldest-first). It does not mention authentication or rate limits, but the core behavioral traits are well disclosed.

  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 a single, coherent paragraph of three sentences with the main purpose front-loaded. It is slightly lengthy but each sentence adds value (decryption behavior, error handling, sorting). Could be trimmed slightly but remains effective.

  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 tool's complexity (bidirectional DM fetch, decryption, error handling), the description covers the core behavior and return format (sorted oldest-first). No output schema exists, but the description provides sufficient context for correct invocation. Minor gap: does not specify whether the decrypted content is returned as plaintext strings.

  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?

  All three parameters have descriptions in the schema (100% coverage). The tool description adds minimal nuance: it mentions that limit is per direction and since is a Unix timestamp. This is helpful but does not significantly extend the schema's meaning, so baseline score 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 clearly states the tool's action ('Fetch + decrypt the DM thread') and specifies the resource ('between the configured signer and a counterparty'). It distinguishes from siblings like nostr_send_dm (sending) and nostr_decrypt_dm (single decryption) by describing a bidirectional, sorted thread get with decryption.

  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 usage for retrieving DM threads with a specific counterparty, but does not explicitly state when to use this tool versus alternatives such as nostr_query_events or nostr_decrypt_dm. No when-not or conditions are provided, leaving the agent to infer context.

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

• nostr_encodeA
  4/5.0
  Behavior3/5

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

  The description discloses important behavioral traits: local-only execution and prohibition of nsec encoding. However, it lacks details about error handling, return format, or input validation beyond what the schema provides. Without annotations, this is adequate but not comprehensive.

  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 extremely concise—two sentences that efficiently convey purpose, scope, and constraints. No unnecessary words 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 tool's simplicity and the schema's richness, the description covers the core purpose and constraints. The output format is implied by 'bech32 form', but a brief mention of the return value (e.g., 'returns a bech32-encoded string') would complete the picture.

  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 description adds minimal value beyond the already detailed input schema (100% coverage). It repeats some parameter constraints (e.g., type values) but does not provide additional semantic guidance for using parameters together.

  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 the action ('Encode' a raw NIP-19 record) and the output format ('bech32 form'). It explicitly lists supported types (npub, note, nevent, naddr, nprofile), differentiating it from sibling tools like nostr_decode.

  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 provides clear usage context: it's a local-only operation with no network call, and explicitly warns against using nsec encoding. While it doesn't explicitly name alternatives, the context implies this tool is for encoding public data, and private keys should be handled separately.

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

• nostr_delete_eventA
  4.1/5.0
  Behavior4/5

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

  Discloses soft delete nature, relay honor uncertainty, and permission requirement. Without annotations, description carries burden and does well.

  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 sentences, each essential: purpose, behavior, prerequisite. No fluff, front-loaded.

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

  Completeness3/5

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

  Adequate for a simple delete tool but lacks return value description. Output schema absent, so description could mention what response looks like.

  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 covers both parameters completely; description adds minimal value (e.g., reason goes into content field). Baseline 3 given full 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?

  Clearly states 'Publish a NIP-09 kind:5 deletion request', specifying verb, resource, and protocol standard. Differentiates from siblings like nostr_publish_event by focusing on deletion.

  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?

  Provides context on soft deletion, relay behavior, and prerequisite (allowed kinds). Missing explicit when-not-to-use, but guides agent effectively.

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

• nostr_publish_addressable_eventA
  4.2/5.0
  Behavior4/5

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

  No annotations provided, so the description carries full burden. It discloses automatic d-tag setting and replaceability behavior. However, it does not mention authentication, relay acceptance, or error handling, which are relevant for a publish tool.

  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, front-loaded with the core purpose, and no redundant content. Every sentence provides essential 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?

  With 4 parameters and no output schema, the description covers the key aspects: kind range, automatic d-tag, replaceability, and market-specific examples. It could mention event signing or failure behavior, but overall sufficient for the complexity.

  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%, giving a baseline of 3. The description adds context about marketplace kinds and replaceability, but mostly repeats schema info (d_tag sets d tag). No additional 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 clearly states it publishes parameterized-replaceable events (kind 30000–39999) and specifically calls out NIP-15 marketplace use cases (stalls and products). It distinguishes itself from siblings like nostr_publish_event, which publishes regular events.

  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 explains that this tool is the 'load-bearing bridge' for marketplace events and notes republishing behavior. While it does not explicitly list when not to use it, the context strongly implies it is for addressable events only, providing adequate guidance for an agent.

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

• nostr_get_profileA
  4.3/5.0
  Behavior4/5

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

  The description covers primary behavior: returns parsed JSON content, source event id, timestamp, and null if not found. It lacks explicit mention of read-only nature or error handling, but the 'fetch and parse' language implies a safe read operation. Since no annotations are provided, the description carries the full burden and does a good job.

  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 with no wasted words. The first sentence states purpose and return, the second handles the null case. Structure is front-loaded and efficient.

  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, one-parameter tool with no output schema, the description is complete. It covers input format, relationship to sibling tools, return values (including specific fields), and the null case. No significant gaps remain.

  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% with a clear parameter description. The tool description reinforces the parameter's purpose but does not add significant new meaning beyond what the schema already 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 explicitly states the action ('Fetch and parse a NOSTR profile') and the resource ('kind:0 metadata'). It distinguishes itself from the general nostr_query_events by labeling itself a convenience wrapper, making its specific purpose clear.

  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 implies usage when you want a single profile by pubkey or npub, and contrasts with the more general nostr_query_events. However, it does not explicitly state when not to use this tool or list alternatives among the many sibling tools.

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

• nostr_list_relaysA
  4.3/5.0
  Behavior3/5

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

  With no annotations, the description carries full burden. It indicates a read operation (list), but does not disclose potential side effects, authentication requirements, or rate limits. The behavior is simple enough that this is minimally adequate.

  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 a single sentence of 12 words, containing no filler or redundancy. Every word is informative and earns its place.

  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?

  Despite having no output schema, the description explains what the tool returns (a list of relays with their connection status), which is sufficient for a simple listing operation. No additional context is needed.

  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?

  There are no parameters, and the schema coverage is 100% (empty). The rubric sets a baseline of 4 for zero-parameter tools, and the description does not need to add parameter information.

  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 the verb 'List' and the resource 'configured relay pool', and adds specific detail about returning connection status. It is distinct from sibling tools which focus on profiles, events, and DMs.

  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 implies the tool is used to get an overview of configured relays and their status. No alternatives exist among siblings, so explicit when/when-not guidance is unnecessary. However, no prerequisites or context are provided.

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

• nostr_publish_eventA
  4.3/5.0
  Behavior4/5

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

  No annotations provided, but the description lists safety pipeline steps (read-only gate, signer presence, kind allowlist, rate limit, optional confirmation), disclosing behavioral traits.

  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 that are front-loaded: first defines core function, second adds context. Every sentence earns its place.

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

  Completeness3/5

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

  No output schema; description does not mention return value (e.g., event ID) or signing prerequisites. Missing some completeness for a primitive write tool.

  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%, but the description adds value with examples for kind (common kinds), tag structure, content type, and created_at constraints.

  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 it signs and broadcasts a raw NOSTR event of any allowed kind, and distinguishes itself as the primitive write tool with 'convenience wrappers around this'.

  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?

  Provides context that it's the primitive tool and mentions the safety pipeline, but does not explicitly state when to prefer convenience wrappers 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.

• nostr_verify_nip05A
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description bears full burden. It explains the HTTP fetch, JSON lookup, verification logic, and relay hints. It does not mention failure modes or performance, but provides substantial transparency.

  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?

  Description is a single paragraph that covers key points without excess. It could be slightly more structured, but it remains concise and informative.

  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?

  No output schema, so description must hint at returns. It mentions verified flag, resolved pubkey, and relay hints, which is reasonably complete for a verification tool. Lacks explicit return structure.

  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% with param descriptions. Description adds meaning beyond schema by explaining the fetch URL and lookup process, providing context for how parameters are used.

  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 it verifies a NIP-05 identifier and resolves to a pubkey, using specific verb 'Verify' and resource 'NIP-05 identifier'. It distinguishes from sibling tools like nostr_get_profile by focusing on verification.

  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 explains when to use the tool (to verify a NIP-05 identifier) and details behavior with and without expected_pubkey. It does not explicitly state when not to use or compare to siblings, but context is clear.

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

• nostr_confirm_publishA
  4.4/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses key behaviors: token consumption (single-use), re-running of the safety pipeline (read-only, signer, kind allowlist, rate limit, dm allowlist), and dispatch based on the issuing tool. No contradictions with annotations exist.

  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 two dense sentences with no wasted words. It front-loads the core purpose and immediately covers conditions, token behavior, and dispatch logic. Every sentence adds value.

  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 one-parameter tool, the description covers conditions, token lifecycle, safety pipeline, and dispatch. However, it does not describe the return value or expected response, which would improve completeness. No output schema exists to compensate.

  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% and the schema description already states the token's purpose ('Confirmation token returned by a previous write tool call'). The tool description adds only minor context ('one-time token'), not substantial new parameter meaning beyond the schema.

  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 the tool executes a previously-prepared signed publish using a one-time token, distinguishing it from sibling tools that create the signed publish (e.g., publish_event, send_dm). The verb 'Execute' and resource 'signed publish' are specific and unambiguous.

  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 the tool is meaningful (NOSTR_REQUIRE_CONFIRM=true or after publish_metadata) and explains that the token is single-use, providing clear context. However, it does not explicitly state when NOT to use it or mention direct alternatives, though sibling tools imply the workflow.

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

• nostr_decrypt_dmA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses auto-detection of NIP-44 vs NIP-04, the tool gate, and confidentiality concerns. It does not detail error behavior or authentication requirements, but the provided information is adequate for a decryption tool.

  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 sentences, each essential: core function, usage context, and technical detail with a warning. No redundancy, perfectly 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?

  Given no output schema and three parameters, the description covers purpose, usage, and behavioral traits. It lacks explicit mention of the return value format (plaintext string) and error handling, but the tool is straightforward enough that these are minor gaps.

  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 baseline is 3. The description adds concrete context for the version parameter (auto-detection) beyond the schema's enum explanation, providing practical guidance.

  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 the tool decrypts a single DM ciphertext, specifying the resource (DM ciphertext) and action (decrypt). It distinguishes from siblings by noting it's useful when already having a kind:4 event from nostr_query_events, avoiding confusion with send/list 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 provides clear context on when to use (when you have a kind:4 event) and mentions the NOSTR_DM_TOOLS_ENABLED gate and confidentiality surface. It does not explicitly state when not to use, but the context is sufficient for an AI agent.

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

• nostr_get_pubkeyA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description fully bears the burden. It discloses error behavior for missing signer and blocking behavior for NIP-46 handshakes, which is valuable transparency beyond the tool's basic function.

  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, each adding distinct value: first states the output and error condition, second adds blocking detail. No wasted words.

  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 no parameters, no output schema, and no annotations, the description covers the essential behavioral aspects (error, blocking) and output format. It is sufficient for a simple tool.

  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?

  There are zero parameters and schema coverage is 100%, so baseline is 4. Description adds no parameter info, but none 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 explicitly states it returns the configured signer's public key in hex and npub formats. It distinguishes from siblings like nostr_get_profile by focusing on the signer's key rather than a profile.

  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 indicates when to use it (to get the signer's public key) and error conditions (no signer configured). While it doesn't explicitly state when not to use it, the sibling list makes it clear this is the only tool for this purpose.

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

• nostr_decodeA
  4.5/5.0
  Behavior4/5

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

  Discloses that it's a local operation (no network call) and that decoding nsec is refused by default unless an environment variable is set. This is important safety information. Lacks details on output format or error handling, but overall good.

  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, front-loaded with purpose, and additional behavioral detail in the second. No redundant information; every word contributes.

  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 decode tool with no output schema, it mentions 'raw fields' but doesn't specify the structure. However, given the simplicity and the list of id types, the output is somewhat implied. Could be slightly improved by noting the output fields (e.g., prefix, hex, relays for nevent).

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

  Parameters5/5

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

  The input schema has 100% coverage with a description that already explains the bech32 string type and the nsec guard. The tool description adds context by listing the specific id types and reinforcing the safety behavior, adding value beyond the schema.

  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?

  Clearly states it decodes NIP-19 bech32 identifiers into raw fields, listing the id types (npub/nsec/note/nevent/naddr/nprofile) and noting it's local-only. This distinguishes it from siblings like nostr_encode (which does the opposite).

  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?

  Tells when to use (to decode identifiers) and provides important context about nsec decoding with a guard. While it doesn't explicitly state alternatives or when not to use, the tool is unique enough that usage is clear.

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

• nostr_send_dmA
  4.6/5.0
  Behavior4/5

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

  Describes encryption behavior and default version, and discloses gating conditions. No annotations exist, so description carries full burden. Could be improved by mentioning return value or success/error behavior, but current detail is adequate for a send operation.

  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, no redundancy. Each sentence adds value: first states core purpose, second provides version guidance and gating. Front-loaded and efficient.

  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 no output schema and no annotations, description covers encryption, version choice, gating, and future alternative. Missing return value details, but overall sufficiently complete for a DM send tool.

  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%, baseline 3. The description adds context beyond schema by clarifying default encryption and advising when to use nip04 for legacy compatibility. This enhances understanding of the version parameter.

  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 'Encrypt + send a NIP-04 (kind:4) direct message', specifying the action and resource. It distinguishes from sibling tools like nostr_list_dms and nostr_decrypt_dm by focusing on sending, and mentions modern sealed DMs (NIP-17) as a separate future tool.

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

  Usage Guidelines5/5

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

  Explicitly provides when to use each encryption version: 'Defaults to NIP-44 encryption...pass version="nip04" only for legacy compatibility.' Also notes gating conditions (NOSTR_DM_TOOLS_ENABLED, NOSTR_DM_ALLOWLIST, rate limit) and directs users to wait for a future version for modern sealed DMs.

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