Nostr Signer

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

Annotations mark this as a non-read-only, non-destructive, open-world operation. The description adds real context beyond that: the code is short-lived and grants read-only access, and it enumerates concrete side effects that do NOT occur. It stops short of stating auth requirements or what success returns.

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 scope, then a compact exclusion list. Efficient, though the second sentence is somewhat negation-heavy rather than adding positive usage 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?

For a 2-parameter tool with annotations and no output schema, the description covers what the tool does, its limits, and the non-effects an agent might otherwise assume. Missing only return-behavior and auth specifics, which is acceptable given annotation coverage.

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

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

Schema coverage is 100%, so both parameters (code, confirm_browser_sign_in) are fully documented in the schema. The description contributes only the 'short-lived, read-only' characterization of the code, so the baseline 3 applies.

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

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

States a specific verb (sign/approve) and resource (Grynvault account handoff code) and clarifies the outcome (the browser tab receives its own dashboard). It also fences scope against siblings by ruling out invoice creation, event publishing, settlement changes, and wallet custody, though it does not name a specific alternative tool.

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

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

Usage is only implied: the negative list (does not create invoice, publish event, etc.) steers away from some siblings, and the schema param hints at the 'user asked to sign the displayed code' trigger. There is no explicit when-to-use or named alternative in the description text itself.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the safety profile is partly covered. The description adds a meaningful constraint ('Never accepts an nsec'), which is valuable security context. It doesn't explain what the caller does with the returned URI, TTL, or relay behavior, leaving moderate 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?

Two short sentences, front-loaded with the key action and the security caveat. Efficient with no wasted wording.

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

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

For an advanced pairing tool with no output schema and no annotations covering the URI format, the description should mention what the caller receives and any relay/timeout behavior. The 'Never accepts an nsec' note is useful but the overall picture is incomplete for a pairing flow.

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% and the single parameter 'relays' is undocumented in both the schema and the description. The description could have clarified the optional relay list format and limits, but the tool has only one optional parameter, so the baseline for limited-parameter tools keeps this at a middle score.

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

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

States a specific verb+resource: creates a nostrconnect:// URI for the user to scan or open in a remote signer. The 'Advanced fallback' framing helps distinguish it from the more typical sibling tools like connect_bunker. However, it doesn't explicitly name which sibling to use instead in the normal case.

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?

Labeling it an 'Advanced fallback' implies it's not the default path and should be used when other pairing methods fail, but it doesn't name the alternative (e.g., connect_bunker) or state the condition that triggers fallback. Usage context is implied rather than 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?

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is partly covered. The description still adds non-obvious behavioral constraints: it refuses nsec input, and it warns that connection secrets must not be placed in chat, which shapes how an agent should route the user.

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

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

Three short, front-loaded sentences, each carrying distinct information (precondition, preferred alternative, input rejection). No filler, no repetition of the tool name.

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 state-changing connection tool with no output schema, the description covers the critical when/when-not and input-security concerns. It omits what happens after a successful connect (persistence, follow-up with get_signer_status or disconnect_signer), which would help an agent plan the next step.

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% for the single required parameter, so the description has to compensate. It does so by naming the accepted format ('bunker:// URI') and stating a hard negative constraint ('Never accepts an nsec'), which is more than the bare 'string' in the schema conveys; the 8192 max length remains undocumented.

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

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

States a specific verb and resource ('Connect a bunker:// URI'), so the agent knows exactly what happens. It does not explicitly name the sibling it differs from (e.g. begin_nostrconnect_pairing, get_setup_url), but the URI-type specificity makes it reasonably distinguishable from surrounding signer tools.

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

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

Gives an explicit precondition ('only when the user knowingly supplied it') and an explicit preferred alternative (the local setup page) with a rationale. This is exactly the when-to-use / when-to-prefer-something-else guidance the dimension asks for.

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

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

Annotations already declare non-readonly, non-destructive and open-world. The description adds real value beyond them: it requires explicit user confirmation, clarifies it signs an authorization, creates exactly one pending invoice, and enumerates non-effects (no pay/settle/activate/identity proof).

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 confirmation gate, then the action, then the negative scope. No waste; every clause carries information.

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

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

For a two-parameter mutation with no output schema, the description covers the confirmation requirement, the produced artifact (one pending invoice), and what it deliberately does not do. Only the origin/meaning of operation_id remains slightly implicit.

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

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

Schema coverage is only 50%: confirm_invoice_creation is documented in-schema and the description reinforces its 'explicit confirmation' meaning. operation_id is undocumented in both places, though 'the prepared authorization' implies it references a prior prepare call. Partial compensation, baseline 3.

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

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

States a specific verb (sign + create) and resource (a pending NIP-05 name@frontiercrown.com invoice), naming the exact artifact. The contrast with prepare_grynvault_nip05_invoice (it consumes 'the prepared authorization') and with the supporter-invoice sibling is clear from the resource name.

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

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

Gives a clear precondition ('after separate explicit user confirmation') and bounds the action with negatives ('does not pay, settle, activate, or prove identity'). It implies but never explicitly names prepare_grynvault_nip05_invoice as the required preceding step, 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.

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

Adds value beyond annotations: clarifies it creates exactly one pending invoice, does not pay it, and never treats a redirect as settlement. These are meaningful behavioral caveats beyond readOnlyHint/destructiveHint/openWorldHint. Missing detail on reversal/irreversibility but otherwise solid.

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

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

Two tight sentences, front-loaded with the precondition and the core action, no filler. Every clause carries 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?

No output schema, no annotations covering mutation semantics beyond the hints, and half the parameters undocumented. Description covers the safety pattern well but leaves the operation_id linkage and return behavior unclear, which matters for a mutation 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?

Schema coverage is only 50% (operation_id has no description). The description references 'the prepared authorization' and 'exactly one' invoice, vaguely implying operation_id's role, but doesn't explain that operation_id ties to a prior prepare call or that confirm_invoice_creation must also be true. Fails to compensate for the coverage gap.

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?

Specific verb (create) and resource (pending Grynvault supporter invoice), clearly distinct from prepare_grynvault_supporter_invoice by the verb 'create' vs. 'prepare'. It doesn't explicitly name the prepare sibling, but the create/prepare distinction and the mutating nature are clear.

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?

States the precondition ('After separate explicit user confirmation') and invokes the prepare workflow implicitly ('sign the prepared authorization'). The when-not is partially covered by noting it doesn't pay the invoice, but no alternative tool is named when a caller hasn't prepared yet.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the specific blast radius: the signer session and all prepared (unsigned) events are discarded. That is real behavioral value beyond the annotations, though it does not cover reconnection or recovery behavior.

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 tight sentence that front-loads the action and enumerates the affected state with zero filler.

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

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

For a destructive, parameterless-in-effect tool with annotations covering the safety profile and a schema enforcing explicit user confirmation, the definition is nearly complete. Minor gaps remain around whether the session can be restored and what side effects follow.

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

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

Only one parameter and schema description coverage is 100%, so the schema itself fully documents confirm_disconnect and its approval requirement. The description adds no syntax or semantic detail about the parameter, so the baseline of 3 applies.

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

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

The description uses a concrete verb (forget) plus the exact resources affected (in-memory signer session and all prepared events), which is far more specific than the tautological title. It does not name or contrast with any sibling tool, so it stops short of a 5.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as get_signer_status or reconnecting afterwards. The agent must infer the appropriate context entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds real value beyond that: the operation depends on a 'short-lived signed authorization' and requires user-approved signing, which the annotations don't convey. Not a 5 since auth failure behavior and rate limits aren't 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?

Two tight sentences front-load the resource and immediately scope out the invoice siblings. Nearly every word earns its place; minor redundancy between the auth framing and the schema's parameter description.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description covers purpose, scoping, and the authorization precondition adequately. An agent has enough to call it correctly, though return-shape expectations and the auth lifetime details remain unspecified.

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?

There is only one parameter and schema description coverage is 100%, and the schema itself spells out the confirm_account_access semantics (true only after user approved signing). The description reinforces this precondition but adds nothing the schema lacks, so baseline 3 applies.

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

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

States a specific verb (Read) and resource (the connected Nostr identity's Grynvault supporter, payment, and NIP-05 dashboard), and explicitly negates the invoice siblings by saying it 'does not create an invoice or change settlement.' An agent can distinguish this from create_grynvault_supporter_invoice / prepare_grynvault_* without opening schemas.

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

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

The negation clause clearly carves out when NOT to use this (creating invoices, changing settlement), and the signed-authorization framing implies the required user approval precondition. It doesn't name a specific sibling alternative to route to, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true, non-destructive and closed-world, so the safety profile is covered. The description adds one useful behavioral detail — the key comes from the currently paired signer — but says nothing about failure when no signer is paired or about the key's encoding.

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 with no filler, and the scope qualifier is placed where it matters.

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

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

With no output schema, the description carries the burden of describing the return value, and it only says 'the public key' without format or encoding. For a zero-parameter read tool this is serviceable but leaves the agent guessing about the response shape.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify; baseline 4 applies.

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

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

States a specific verb and resource ('Return the public key') scoped to 'the currently paired signer', which is more precise than the title. It does not explicitly contrast itself with nearby siblings such as get_signer_status, but the action is unambiguous.

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

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

No indication of when to call this versus alternatives like get_signer_status or connect_bunker, and no prerequisite stated (e.g., that a signer must be paired first). The agent must infer the context entirely.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds useful context beyond that: the page is loopback-only and supports two distinct signer flows. It does not say whether invoking it opens a browser or merely returns a URL, nor what the caller does next.

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 with the action verb front-loaded and no filler. Every clause (loopback-only, NIP-07, NIP-46) carries information.

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

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

With no parameters and no output schema, the description does need to convey what comes back, and it does — a loopback page for signer connection. The only gap is that it doesn't state what the agent should do with the returned URL (e.g. surface it to the user to open), which slightly weakens end-to-end completeness.

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

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

The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. There is no parameter-related meaning the description needed to supply.

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 gives a specific verb (Return) and resource (the loopback-only setup page for connecting a NIP-07 extension or NIP-46 signer), which is concrete and actionable. However, the crowded sibling set (connect_bunker, begin_nostrconnect_pairing, approve_grynvault_browser_handoff) all touch signer connection, and the description does not explicitly say how this URL-returning tool differs from those.

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 implies the use case — getting the page used to connect a signer — but never states when to call this versus connect_bunker or begin_nostrconnect_pairing, nor any prerequisites or sequencing. Usage is left to inference from the two signer types mentioned.

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

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

Annotations already declare readOnlyHint=true, non-destructive and non-open-world, so the safety profile is covered. The description adds only the signer-type scope (NIP-07/NIP-46). It does not describe the return shape (e.g., boolean vs. signer type), which matters for an agent deciding its next step.

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, well-front-loaded sentence with no filler. Nothing could be removed without losing 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 simple zero-param read tool with annotations and no output schema, the definition is adequate but thin. Without an output schema, an agent would benefit from knowing what 'status' returns, which the description does not provide.

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?

Zero parameters, so the baseline is 4. The description needs no param documentation and correctly carries none.

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

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

States a specific verb+resource: 'Check whether a ... signer is connected.' Clearly distinguishes the read-only status query from siblings like connect_bunker, disconnect_signer, and sign_event. It does not name those siblings explicitly, which caps it below a 5.

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

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

Usage is strongly implied: use it to find out if a signer is already connected before signing or connecting. But there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives such as connect_bunker, so it sits at the minimum-viable level.

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?

Adds context beyond annotations: it discloses that plaintext is 'sensitive' and gated on explicit user intent, which is meaningful behavioral guidance for a decrypt operation. Annotations mark openWorldHint=true and readOnlyHint=false but don't convey the user-consent gate; this adds real value, though it doesn't describe failure modes or rate limits.

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

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

Two tight sentences, action first then behavioral constraint. No filler, and the important gating caveat is front-loaded enough to be noticed.

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

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

No output schema, so the description should ideally note that plaintext is returned (it does mention 'Returns sensitive plaintext'), which helps. However it omits error behavior, what happens if confirm_decryption is false, and doesn't cover the pubkey/ciphertext parameter roles fully. Adequate but with gaps for a security-sensitive 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?

Schema coverage is 33%, so the description must compensate. It explains the purpose of confirm_decryption indirectly via 'explicit user intent' but doesn't clarify that this must be set to true, nor does it explain the pubkey or ciphertext parameters beyond what the schema's types imply. Baseline adjusted for partial coverage.

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

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

States a specific verb (decrypt), resource (NIP-44 ciphertext), and mechanism (paired signer). Distinguishes from nip44_encrypt by naming the decrypt direction. Doesn't distinguish from sign_event-type siblings beyond the crypto operation, but the NIP-44 reference is specific enough.

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 'only after explicit user intent' implies a precondition for use, which is useful. But it doesn't name alternatives or specify when-not to call, and offers no guidance on how the confirm_decryption flag interacts with the caller's workflow beyond the implied 'ask the user first'.

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

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

Annotations already convey the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new context: plaintext is never logged (a privacy guarantee) and the caller must have explicit user intent. It delegates the operation to an external paired signer, which the annotations do not convey. It stops short of describing rate limits or output format.

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 tightly packed sentences with no waste; the purpose leads and the privacy/intent constraints follow. Every clause earns its place.

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

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

For an encryption tool with no output schema and adequate annotations, the description covers purpose, prerequisite, privacy, and gating condition. It could say more about the returned ciphertext or failure modes, but nothing essential for correct invocation is missing.

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

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

Schema coverage is low (33%), with only confirm_encryption documented in the schema. The description implies pubkey is a recipient key and plaintext is the input, which adds some meaning, but it never explains the confirm_encryption flag or the 64-hex pubkey format, leaving the coverage gap largely uncompensated.

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

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

States a specific verb and resource — 'NIP-44 encrypt plaintext for a public key' — and names the mechanism (NIP-44) and the actor (the paired signer). It is immediately distinguishable from the sibling nip44_decrypt and from sign_event.

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 prerequisite ('the paired signer') and the gating condition ('requires explicit user intent') are implied, but no alternatives are named and no explicit when-not guidance is given. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful workflow context (user review step, no sign/publish) beyond annotations, but says nothing about validation failure behavior or what binding means.

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

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

Three short sentences, front-loaded with the core action, then the boundary, then the user-facing instruction. No waste, though the third sentence is more instruction than description.

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 1-param, no-output-schema tool with annotations covering safety, the description covers the workflow role adequately. Missing: what 'bind' means concretely, what happens on validation failure, and no mention of the prepare_note sibling in the same prepare family.

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 single param is a nested object with 4 required subfields and additionalProperties=false, but the schema itself documents structure and constraints (kind range, array limits, content max length) via JSON Schema. Description adds no param guidance, so baseline 3 applies since structure is machine-readable.

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

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

States a specific verb (validate/bind) and resource (exact unsigned Nostr event) for user review. Distinguishes itself from sign_event and publish_event by naming both boundaries, though it doesn't explicitly name the prepare_note sibling it complements.

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?

Clear about when to use: before requesting a signature. Explicitly excludes signing and publishing, routing the agent to sign_event/publish_event for those steps. No exclusion for prepare_note alternatives, but the workflow ordering is clear.

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

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

Annotations already declare readOnly and non-destructive, and the description is consistent with them while adding valuable context: the invoice amount is fixed at exactly 2,000 sats and no state is mutated (no signing, reserving, settling). It omits what the authorization result looks like and any auth/prerequisite 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?

Two tightly constructed sentences with the positive action front-loaded and the negative scope trailing. 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?

With no output schema, the description still conveys the key output fact (a 2,000-sat invoice authorization) and full side-effect scope. Minor gap: return shape and whether the caller must pass the result to another tool for signing/creation.

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 carry the parameter meaning. It adds that the input is a name@frontiercrown.com identifier subject to normalization, but does not clarify whether the caller passes the full identifier or only the local part, nor how normalization changes it.

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?

Names specific verbs (check, normalize, prepare) and the exact resource (a name@frontiercrown.com NIP-05 invoice authorization), and implicitly separates itself from the create_* sibling by stating it prepares rather than creates.

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 explicit 'does not sign, reserve the name, create, pay, or settle an invoice' clause tells the agent the boundary conditions and routes genuine creation/payment to the create_* siblings. It stops short of naming the alternative tool directly, so it is strong but not fully explicit routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, but the description adds meaningful context beyond them: the request is 'short-lived' and explicitly does not sign/create/pay/settle. For a prepare-step tool this negative-scope disclosure is genuinely useful for understanding the security boundary.

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

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

Two tight sentences: the action is front-loaded, then the negative scope. No filler, and every clause carries information.

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

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

With no output schema and only two parameters, the description covers purpose, scope limits, and the plan/amount semantics adequately. It leaves minor gaps around the exact returned artifact and any signing prerequisites, but nothing critical for a read-only prepare 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?

Schema description coverage is 0%, so the description must carry the load, and it does: it maps the two plan modes (one-time donation versus fixed 2,100-sat 30-day membership) and states the donation range of 21 to 1,000,000 sats, matching the donation_sats min/max. It never names the 'plan' or 'donation_sats' fields, but the option semantics are substantially conveyed.

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

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

States a specific verb (prepare) and resource (signed-authorization request) and disambiguates from the create/sign/pay/settle toolchain by negation, which helps separate it from the sibling create_grynvault_supporter_invoice. However, 'signed-authorization request' is somewhat jargon-heavy and the sibling is not named explicitly.

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

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

The phrase 'Does not sign, create, pay, or settle an invoice' implies this is the preparatory step before signing/creation, giving implied usage context. But it never states explicitly when to choose this over create_grynvault_supporter_invoice or what precedes/follows it, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context beyond annotations: it produces an 'unsigned' note, it 'binds' it, it's for 'user review', and critically it 'does not sign or publish', clarifying that signing/publishing is a separate step. This is a helpful clarification of a non-obvious prepare/commit split.

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 result, followed by the key boundary (does not sign/publish). No waste.

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

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

For a single-param, annotated, no-output-schema tool, the description covers the essential: what it creates, that it's unsigned, and the non-signing boundary. A brief note about the expected next step (sign_event) would make it fully complete, but what's present is sufficient to call correctly.

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

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

Schema coverage is 0%, so the description should compensate, but the single 'content' parameter is self-evident in meaning. The description doesn't explain content constraints (maxLength 65536, the kind:1 format implied). With one obvious parameter and no description coverage, baseline 3 applies.

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

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

Clear specific verb+resource: 'Prepare and bind an exact unsigned kind:1 note for user review.' It states exactly what is produced (an unsigned note) and the kind (1). It distinguishes itself from publish_event/sign_event by stating 'This does not sign or publish', though it doesn't explicitly name prepare_event, its closest sibling.

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

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

The description implies a workflow (prepare → review → sign/publish) by stating what it doesn't do, which helps an agent infer when to use it. But it never explicitly names alternatives like prepare_event or sign_event, nor states prerequisites. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the agent knows this mutates external state. The description adds the explicit-user-intent requirement and the 'previously verified' precondition, which is real added context. It does not, however, disclose the irreversibility of publishing to relays or failure behavior, which matters for a destructive tool.

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

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

Two tight sentences with the action verb front-loaded and no filler. Efficient, though 'previously verified' and 'separate' are slightly underspecified for the space saved.

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

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

For a destructive, open-world publish operation with no output schema and only partial parameter documentation, the description is too sparse. An agent still lacks return/failure behavior, whether published events can be retracted, and how relays defaults are resolved.

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 only 33% and the description supplies no parameter-level detail at all. The intent_id and relays parameters are undocumented in both schema and description, and the description does not compensate for the coverage gap as required when coverage is low.

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

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

States a specific verb (publish), resource (signed event), and destination (configured relays), and the phrase 'previously verified signed event' implies the prepare/sign prerequisite. It does not explicitly name sibling tools like sign_event or prepare_event, so it is clear but not fully differentiated from siblings in-text.

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

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

'Requires separate explicit user intent' gives a precondition for invoking the tool, which is useful context. However it names no alternative or exclusion condition, and the workflow relationship to sign_event/prepare_event is only implied. Usage is inferred rather than spelled out.

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

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

Annotations already declare readOnly, openWorld, and non-destructive, so the safety profile is covered. The description adds 'bounded', 'verified', and 'from selected relays', which hints at result constraints and relay behavior, but doesn't explain verification meaning or relay semantics.

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, fully front-loaded with the key action and constraints. 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?

A read-only query with annotations and no output schema needs the description to clarify the query semantics and parameters. It covers scope but leaves five undocumented parameters unexplained, which is a notable gap for a filtering 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?

Schema coverage is 0%, so the description must carry parameter meaning, but it only implies a bounded/selected-relay query. None of the five parameters (kinds, limit, since, relays, authors) are explained, leaving the agent to infer semantics from schema structure alone.

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?

Specific verb+resource: 'Read a bounded set of verified public profile or note events from selected relays.' Clearly distinguishes from siblings like publish_event and prepare_event, which involve writing/constructing rather than reading.

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

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

No when-to-use guidance or alternatives named. It doesn't explain when to prefer querying versus using a prepared event, nor the use case for the bounded/verified constraints.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds meaningful context beyond those: it requires explicit user intent, signs only the exact bound event, and 'never publishes'. It doesn't cover failure modes or what the signer returns, but the safety-relevant behavior is 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.

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

Two short sentences, tightly front-loaded with the action and the key constraints ('explicit user intent', 'never publishes'). 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 signing operation it covers the safety-critical points (user intent required, no publish), but omits the relationship to prepare_event, what the signer approval flow looks like, and what happens on rejection. No output schema exists, so some return-shape context would have helped.

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

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

Schema coverage is 50%; confirm_signature is documented in schema but intent_id has no schema description. The description implies intent_id refers to 'a fresh intent' but adds no format, provenance, or lifecycle detail beyond what the schema already conveys for the boolean.

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?

Clear verb ('sign') and resource ('the exact event bound to a fresh intent'), distinguishing it from siblings like prepare_event and publish_event. However, it doesn't explicitly name where the event comes from (presumably prepare_event) or how it differs from approve_grynvault_browser_handoff, leaving some differentiation to inference.

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?

Implies usage requires 'explicit user intent' and a fresh intent, but doesn't state when to call this vs prepare_event first, or vs publish_event. No explicit preconditions chain is given, so an agent must infer the workflow.

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